Python
Prev  Chapter 4. Scripting  Next

Python

This module provides bindings to the Python programming language. Basic usage in the context of SciDAVis will be discussed below, but for more in-depth information on the language itself, please refer to its excellent documentation.

Getting Started

Make sure your current project uses Python as its interpreter by selecting the menu point Scripting->Scripting Language and double-clicking on "Python" in the resulting dialog (if the dialog appears, but does not contain the "Python" item, your installation of SciDAVis has been compiled without Python support). Next, open a Notes window and enter print "Hello World!". Position the cursor anywhere on this line and press Ctrl+J, or select "Execute" from the context menu. The string "Hello World!" should appear below the line you entered. Congratulations, you've made contact with Python! You can also enter more complex code fragments, such as function or class definitions, in which case you have to select the whole code block before executing it.

You can also use Notes windows as a handy calculator. Enter a mathematical expression on a line of its own - say, 5*sin(pi/2). Press Ctr+Enter, or select "Evaluate" from the context menu. You are rewarded by a new line, stating (to general astonishment), that the result of evaluating your expression is #> 5. If you have SciPy and/or PyGSL installed, you will have immediate access to a huge number of interesting functions, browseable via the sub-menu "Functions" of the context menu. Pressing Shift+F1 while in this menu will give you a short description of the current function. The advantage of only executing/evaluating single lines or selections on request is that you can freely mix text and calculations within a Notes window.

Another particularly handy place for using Python code are column formulas. These work just like evaluating expressions in Note windows, with the additional advantage of some pre-defined variables: i (the row currently being computed), j (the column number), sr (start row), er (end row) and self (the table to which the column being computed belongs; see below for what you can do with it).

If you are already familiar with Python, you might ask yourself at this point if you can use more complicated column formulas than just single expressions (for instance, if:/else: decisions based on the current row number). The answer is: yes, you can. For the benefit of those not familiar with Python, we will give a short introduction to the language before discussing how to do this.

Python Basics

Expressions

Mathematical expressions work largely as expected. However, there's one caveat, especially when switching from muParser: a^b does not mean "raise a to the power of b" but rather "bitwise exclusive or of a and b"; Python's power operator is **. Thus: 

2^3 # read: 10 xor 11 = 01
#> 1
2**3
#> 8

Statements

One thing you have to know when working with Python is that indentation is very important. It is used for grouping (most other languages use either braces or keywords like do...end for this). For example, executing the following: 

x=23
for i in (1,4,5):
	x=i**2
	print(x)

will do what you would expect: it prints out the numbers 1, 16 and 25; each on a line of its own. Deleting just a bit of space will change the functionality of your program: 

x=23
for i in (1,4,5):
	x=i**2
print(x)

will print out only one number - no, not 23, but rather 25. This example was designed to also teach you something about variable scoping: There are no block-local variables in Python.

There are two different variable scopes to be aware of: local and global variables. Unless specified otherwise, variables are local to the context in which they were defined. Thus, the variable x can have three different values in, say, two different Note windows and a column formula. Global variables on the other hand can be accessed from everywhere within your project. A variable x is declared global by executing the statement global x. You have to do this before assigning a value to x, but you have to do it only once within the project (no need to "import" the variable before using it). Note that there is a slight twist to these rules when you define your own functions.

The basic syntax for defining a function (for use within one particular note, for example) is 

def answer():
	return 42

If you want your function to be accessible from the rest of your project, you have to declare it global before the definition: 

global answer
def answer():
	return 42

You can add your own function to SciDAVis's function list. We'll also provide a documentation string that will show up, for example, in the "set column values" dialog: 

global answer
def answer():
	"Return the answer to the ultimate question about life, the universe and everything."
	return 42
sci.mathFunctions["answer"] = answer

If you want to remove a function from the list, execute 

del sci.mathFunctions["answer"]

Note that functions have their own local scope. That means that if you enter a function definition in a Notes window, you will not be able to access (neither reading nor writing) Notes-local variables from within the function. However, you can access global variables as usual.

If-then-else decisions are entered as follows: 

if x>23:
	print(x)
else:
	print("The value is too small.")

You can do loops, too: 

		for i in range(1, 11):
			print(i)

This will print out the numbers between 1 and 10 inclusively (the upper limit does not belong to the range, while the lower limit does).

Hints on Python 2 vs Python 3 usage

In version 1.23 of SciDAVis it was added Python 3 support for scripting. Then, in addition to the differences between Python version 2 and 3 listed here, there are some small tips for users that use non-ASCII characters in python scripts.

When SciDAVis is built against Python 3, it is required to specify the character encoding in the scripting note (at the beginning, preferably) using: 

		# coding=<encoding name>

E. g.: to use the UTF-8 character encoding, add 

		# coding=utf8

to the note.

When SciDAVis is built against Python 2, it is required to specify the character encoding each time you use a non-ASCII character inside a command in the following way: 

		command(unicode("<string to be used>","utf8"))

Some examples are:

- To use the print statement:

		print(unicode("<string to be used>","utf8"))

- To modify X axis title on a graph:

		g = graph("Graph1")
		l = g.activeLayer()
		l.setXTitle(unicode("<desired X title>","utf8"))

- To access a graph whose window name has a non-ASCII character:

		g = graph(unicode("<literal window name>","utf8"))

Evaluation Reloaded

As we've already mentioned above, there's a bit more to evaluation than just expressions. Note that Python itself can indeed only evaluate expressions; the following describes a feature of SciDAVis added on top of Python in order to support more interesting column formulas.

If you use statements (e.g. variable assignments or control structures) in a formula, SciDAVis will assume it to be the body of a function. That is, the following code will not work: 

a=1
a+a

The statement in the first line means that the formula cannot be evaluated as a single expression. Instead, the above code assigns every row in the column the return value of the following function: 

def f():
	a=1
	a+a

However, since Python does not implicitly interpret expressions as something to return, this evaluates to nothing. The correct way to enter formulas with statements in them is to explicitly return something: 

a=1
return a+a

There is a slight catch associated with this strategy. In a Notes window, SciDAVis will allow you to evaluate variable assignments like ee=1.6021773e-19 without complaining - but this will not lead to the result presumably intended, i.e. introducing a shortcut for the elementary charge to be used within the notes window. What actually happens is this: SciDAVis evaluates the function 

def f():
	ee=1.6021773e-19

As mentioned in the Python introduction above, the function f has its own variable scope and (unless it happens to be declared global) the variable ee will only be visible within this scope (instead of the Notes window's scope). The solution is simple: always execute things like assignments and function definitions, never evaluate them.

Mathematical Functions

Python comes with some basic mathematical functions that are automatically imported (if you use the initialization file shipped with SciDAVis). Along with them, the constants e (Euler's number) and pi (the one and only) are defined. Many, many more functions can be obtained by installing SciPy and/or PyGSL.

Table 4.4. Supported Mathematical Functions

Name Description
acos(x) inverse cosine
asin(x) inverse sine
atan(x) inverse tangent
atan2(y,x) equivalent to atan(y/x), but more efficient
ceil(x) ceiling; smallest integer greater or equal to x
cos(x) cosine of x
cosh(x) hyperbolic cosine of x
degrees(x) convert angle from radians to degrees
exp(x) Exponential function: e raised to the power of x.
fabs(x) absolute value of x
floor(x) largest integer smaller or equal to x
fmod(x,y) remainder of integer division x/y
frexp(x) Returns the tuple (mantissa,exponent) such that x=mantissa*(2**exponent) where exponent is an integer and 0.5 <=abs(m)<1.0
hypot(x,y) equivalent to sqrt(x*x+y*y)
ldexp(x,y) equivalent to x*(2**y)
log(x) natural (base e) logarithm of x
log10(x) decimal (base 10) logarithm of x
modf(x) return fractional and integer part of x as a tuple
pow(x,y) x to the power of y; equivalent to x**y
radians(x) convert angle from degrees to radians
sin(x) sine of x
sinh(x) hyperbolic sine of x
sqrt(x) square root of x
tan(x) tangent of x
tanh(x) hyperbolic tangent of x

Accessing SciDAVis's functions from Python

We will assume that you are using the initialization file shipped with SciDAVis.

Establishing contact

Accessing the objects in your project is straight-forward, 

t = table("Table1")
m = matrix("Matrix1")
g = graph("Graph1")
n = note("Notes1")

as is creating new objects: 

# create an empty table named "tony" with 5 rows and 2 columns:
t = newTable("tony", 5, 2)
# use defaults
t = newTable()
# create an empty matrix named "gina" with 42 rows and 23 columns:
m = newMatrix("gina", 42, 23)
# use defaults
m = newMatrix()
# create an empty graph window
g = newGraph()
# create an empty note named "momo"
n = newNote("momo")
# use defaults
n = newNote()

New objects will always be added to the active folder. 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. In order to access other folders, there are the functions 

f = activeFolder()
# and
f = rootFolder()

which can be used to access subfolders and windows: 

f2 = f.folders()[number]
f2 = f.folder(name, caseSensitive=True, partialMatch=False)
t = f.table(name, recursive=False)
m = f.matrix(name, recursive=False)
g = f.graph(name, recursive=False)
n = f.note(name, recursive=False)

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.

Also, every piece of code is executed in the context of an object which you can access via the self variable. For example, entering self.cell("t",i) as a column formula is equivalent to the convenience function col("t").

Working with Tables

We'll assume that you have assigned some table to the variable t. You can access its numeric cell values with 

t.cell(col, row)
# and
t.setCell(col, row, value)

Whenever you have to specify a column, you can use either the column name (as a string) or the consecutive column number (starting with 1). Row numbers also start with 1, just as they are displayed. If you want to work with arbitrary texts or the textual representations of numeric values, you can use 

t.text(col, row)
# and
t.setText(col, row, string)

The number of columns and rows is accessed via 

t.numRows()
t.numCols()
t.setNumRows(number)
t.setNumCols(number)

Column names can be read and written with 

t.colName(number)
t.setColName(col, newName)

Normalize a single or all columns: 

t.normalize(col)
t.normalize()

Import values from file, using sep as separator char and ignoring ignore lines at the head of the file. The flags should be self-explanatory. 

t.importASCII(file, sep="\t", ignore=0, renameCols=False, stripSpaces=True, simplifySpace=False, newTable=False)

After having changed some table values from a script, you will likely want to update dependent Graphs: 

t.notifyChanges()

As a simple example, let's set some column values without using the dialog. 

t = table("table1")
for i in range(1, t.numRows()+1):
	t.setCell(1, i, i**2)
t.notifyChanges()

Working with Matrices

We'll assume that you have assigned some matrix to the variable m. Accessing cell values is very similar to Table, but since Matrix doesn't use column logic, row arguments are specified before columns and obviously you can't use column name. 

m.cell(row, col)
m.setCell(row, col, value)
m.text(row, col)
m.setText(row, col, string)

Also like with tables, there's 

m.numRows()
# and
m.numCols()

Plotting and Working with Graphs

If you want to create a new Graph window for some data in table table1, you can use the plot command: 

g = plot(table, column, type)

type is a number between 0 and 10 and specifies the desired plot type:

0.

Line

1.

Symbols

2.

Line and Symbols

3.

Columns

4.

Area

5.

Pie

6.

Vertical drop lines

7.

Splines and Symbols

8.

Vertical steps

9.

Histogram

10.

Rows

You can plot more than one column at once by giving a Python tuple (see the Python Tutorial) as an argument: 

g = plot(table("table1"), (2,4,7), 2)

If you want to add a curve to an existing Graph window, you have to choose the destination layer. Usually, 

l = g.activeLayer()

will do the trick, but you can also select a layer by its number: 

l = g.layer(num)

You can then add or remove curves to or from this layer: 

l.insertCurve(table, column, type=1)
l.insertCurve(table, Xcolumn, Ycolumn, type=1)
l.removeCurve(curveName)
l.removeCurve(curveNumber)
l.deleteFitCurves()

In case you need the number of curves on a layer, you can get it with 

l.numCurves()

Use the following functions to change the axis attachment of a curve: 


c = l.curve(number)
l.setCurveAxes(number, x-axis, y-axis)
c.setXAxis(x-axis)
c.setYAxis(y-axis)

where number is curve's index, x-axis is either Layer.Bottom or Layer.Top and y-axis is either Layer.Left or Layer.Right 

l.setCurveAxes(0, Layer.Top, Layer.Right)  # modify the first curve in the layer (curve index is 0)
c.setXAxis(Layer.Bottom)
c.setYAxis(Layer.Right)  # attach curve c to the right Y axis

Layers and whole Graphs can be printed and exported from within Python. Before you do this, you would probably want to change layer and axis titles as well as legend texts: 

l.setTitle(title)
l.setXTitle(Xtitle)
l.setYTitle(Ytitle)
l.setLegend(text)

You can also customize the scales of the different axes using: 

l.setScale(int axis, double start, double end, double step=0.0, int majorTicks=5, int minorTicks=5, int type=0, bool inverted=False);

where axis is one of Layer.Left, Layer.Right, Layer.Bottom, Layer.Top, type specifies the desired scale type: 0 for Linear or 1 for Log10 and step 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.

Now, here is how you can export a layer 

l.print()
l.exportToSVG(filename)
l.exportToEPS(filename)
l.exportImage(filename, filetype="PNG", quality=100, transparent=False)

and a graph 

g.print()
g.exportToSVG(filename)
g.exportToEPS(filename)

Fitting

Assuming you have a Graph named "graph1" with a curve entitled "table1_2" (on its active layer), a minimal Fit example would be: 

f = GaussFit(graph("graph1").activeLayer(), "table1_2")
f.guessInitialValues()
f.fit()

This creates a new GaussFit object on the curve, lets it guess the start parameters and does the fit. The following fit types are supported:

  • LinearFit(layer, curve)

  • PolynomialFit(layer, curve, degree=2, legend=False)

  • ExponentialFit(layer, curve, growth=False)

  • TwoExpFit(layer, curve)

  • ThreeExpFit(layer, curve)

  • GaussFit(layer, curve)

  • GaussAmpFit(layer, curve)

  • LorentzFit(layer,curve)

  • SigmoidalFit(layer, curve)

  • NonLinearFit(layer, curve)

    f = NonLinearFit(layer, curve)
f.setParameters(name1, ...)
f.setFormula(formula_string)

  • PluginFit(layer, curve)

    f = PluginFit(layer, curve)
f.load(pluginName)

For each of these, you can optionally restrict the X range that will be used for the fit, like in 

f = LinearFit(graph("graph1").activeLayer(), "table1_2", 2, 7)
f.fit()

After creating the Fit object and before calling its fit() method, you can set a number of parameters that influence the fit: 

f.setDataFromCurve(curve)			change data source
f.setDataFromCurve(curve, graph)		change data source
f.setDataFromCurve(curve, from, to)		change data source
f.setDataFromCurve(curve, from, to, graph)	change data source
f.setInterval(from, to)				change data range
f.setInitialValue(number, value)
f.setInitialValues(value1, ...)
f.guessInitialValues()
f.setAlgorithm(algo) # algo = Fit.ScaledLevenbergMarquardt, Fit.UnscaledLevenbergMarquardt, Fit.NelderMeadSimplex


f.setYErrorSource(ErrorSource, colname) # ErrorSource can be: 0 / Fit.UnknownErrors, 1 / Fit.AssociatedErrors,
2 / Fit.PoissonErrors, or 3 / Fit.CustomErrors
f.setTolerance(tolerance)
f.setOutputPrecision(precision)
f.setMaximumIterations(number)
f.scaleErrors(yes = True)
f.setColor(qt.QColor("green"))			change the color of the result fit curve to green (default color is red)

After you've called fit(), you have a number of possibilities for extracting the results: 

f.results()
f.errors()
f.chiSquare()
f.rSquare()
f.dataSize()
f.numParameters()
f.parametersTable("params")
f.covarianceMatrix("cov")

API documentation

Classes mentioned below that start with "Q" mostly belong to Qt and can be used via PyQt (with the exception of classes starting with "Qwt", which belong to Qwt). If you want to know what you can do with such classes (e.g. QIcon or QDateTime), see the PyQt reference documentation. It's also useful to know that you can call any QWidget method exported by PyQt on instances of MDIWindow (and thus Table, Graph, Matrix and Note).

class AbstractAspect (inherits QObject)

A base class for content of a project. While currently the only AbstractAspect accessible to you is Column, a future release will make more extensive usage of this; probably with some revisions in the design, so only some basic functions are documented (and supported) for now.

col = newTable("my-table",2,30).column("1")
col.setName("abc")
table("my-table").column("2").remove()
index()
Return the 0-based index of the Aspect in its sibling list.
name()
Return the Aspect's name.
setName(string)
Change the Aspect's name.
comment()
Return comment attached to the Aspect.
setComment(string)
Change the comment attached to the Aspect.
icon()
Return the icon (a QIcon) used to designate the Aspect's type; for columns, this is the data type icon in the table header.
creationTime()
Return point in time the Aspect was created by the user (as a QDateTime).
remove()
Remove Aspect from the project (can be undone using Edit->Undo menu).
signal void aspectDescriptionAboutToChange(const AbstractAspect*)
Emitted before the description (name or comment) is changed.
signal void aspectDescriptionChanged(const AbstractAspect*)
Emitted after the description (name or comment) has changed.
signal void aspectAboutToBeRemoved(const AbstractAspect*)
Emitted before the Aspect is removed.

class Column (inherits AbstractAspect)

Represents a column in a table.

In addition to the valueAt()/setValueAt() interface described below, starting with SciDAVis 0.2.4, Y columns support getting/setting row values via the values in the corresponding X column. This is done using Python's item access notation for sequence types (as in col["abc"]).

# basic access
tab = newTable("tabula1",2,20)
col = tab.column("1")
col.setValueAt(1, 123.0)
print col.valueAt(1)
# replacing multiple values at once is more efficient than setting them one at a time
col.replaceValues(5, [11.2, 12.3, 23.4, 34.5, 45.6])
# set a value in the second column based on the content of the first one
# (needs SciDAVis >= 0.2.4)
tab.column("2")[23.4] = 46.8
dest = table("tabula1").column("2")
# also, copying from another column can be done in one go:
dest.copy(col, 5, 2, 10)
columnMode()
A string designating the data type; one of "Numeric", "Text", "Month", "Day" or "DateTime".
setColumnMode(string)
Change the column's data type; argument must be one of "Numeric", "Text", "Month", "Day" or "DateTime".
copy(Column)
Copy complete content of other column, which must have the same data type (mode). Returns a boolean indicating success or failure.
copy(Column,int,int,int)
copy(source, source_start, dest_start, num_rows) copies num_rows values from source, starting to read at row source_start and to write at row dest_start.
rowCount()
Number of rows in the column.
insertRows(int, int)
insertRows(before, count) insert count empty rows before row numbered before
removeRows(int, int)
removeRows(first, count) removes count rows starting with row numbered first
plotDesignation()
Return a string representing the plot designation of the column; one of "noDesignation", "X", "Y", "Z", "xErr" or "yErr".
setPlotDesignation(string)
Set the plot designation. The argument must be one of "noDesignation", "X", "Y", "Z", "xErr" or "yErr".
clear()
Clear content of all cells in the column, marking them as empty/invalid.
isInvalid(int)
Returns boolean indicating whether the given row is marked as empty/invalid.
formula(int)
Return formula used to compute the cell value in the given row.
setFormula(int, string)
Sets formula for the given row to string.
clearFormulas()
Discard all formulas associated with cells.
valueAt(int)
Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "Numeric".
setValueAt(int, double)
Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "Numeric".
replaceValues(int, list of double values)
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.
textAt(int)
Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "Text".
setTextAt(int, string)
Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "Text".
replaceTexts(int, list of strings)
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.
dateAt(int)
Retrieve value of the specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".
setDateAt(int, QDate)
Set value of specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".
timeAt(int)
Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "DateTime".
setTimeAt(int, QTime)
Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "DateTime".
dateTimeAt(int)
Retrieve value of the specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".
setDateTimeAt(int, QDateTime)
Set value of specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".
replaceDateTimes(int, list of QDateTime values)
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.
x()
Returns the X Column associated with this (Y, xErr or yErr) column.
y()
Returns the Y Column associated with this (xErr or yErr) column, or the first Y column associated with this X column.

class MDIWindow (inherits QWidget)

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.

tmp = newTable("temp1", 2, 10)
tmp.setWindowLabel("a temporary table")
tmp.setCaptionPolicy(MDIWindow.Label)
# ...
tmp.confirmClose(False)
tmp.close()
name()
Return the window's name (added in SciDAVis 0.2.3).
setName(string)
Set window's name. IMPORTANT: This was added in SciDAVis 0.2.3, but unfortunately is BROKEN in this release. Usable starting with SciDAVis 0.2.4.
windowLabel()
Returns the comment associated with the window (yes, the confusing name will be fixed in a future release).
setWindowLabel(string)
Set comment associated with the window (yes, the confusing name will be fixed in a future release).
captionPolicy()
Return caption policy (i.e., what to display in the title bar). One of the integer constants MDIWindow.Name, MDIWindow.Label or MDIWindow.Both.
setCaptionPolicy(int)
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.
folder()
Return the folder this window belongs to (an object of class Folder).
confirmClose(boolean)
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.
clone()
Returns a copy of this window. Added in SciDAVis 0.2.4.

class Table (inherits MDIWindow)

Class of table (spreadsheet) windows.

tab = newTable("tabula",2,10)
for j in range(0, tab.numCols()):
    for i in range(0, tab.numRows()):
        tab.column(j).setValueAt(i,i*j)	
tab.normalize()
numRows()
Returns the number of rows of the table.
numCols()
Returns the number of columns of the table.
setNumRows(int)
Sets the number of rows of the table.
setNumCols(int)
Sets the number of columns of the table.
column(string or int)
Returns Column indicated by name (preferred) or 0-based index. For the latter form, keep in mind that inserting, removing or moving columns will break scripts which refer to a specific column by index. Starting with SciDAVis 0.2.4, columns may also be accessed using the [] operator, i.e. using table("table name")[column name or index].
text(string or int, int)
DEPRECATED. Use column(col).textAt(row) or str(column(col).valueAt(row)) instead (depending on the column's mode). CAVEAT: text() indexes are 1-based, while column() and textAt() use more conventional 0-based indexes!
cell(string or int, int)
DEPRECATED. Use column(col).valueAt(row) instead. CAVEAT: cell() indexes are 1-based, while column() and valueAt() use more conventional 0-based indexes!
setText(string or int, int, string
DEPRECATED. Use column(col).setTextAt(row,value) instead. CAVEAT: setText() indexes are 1-based, while column() and setTextAt() use more conventional 0-based indexes!
setCell(string or int, int, double
DEPRECATED. Use column(col).setValueAt(row,value) instead. CAVEAT: setCell() indexes are 1-based, while column() and setValueAt() use more conventional 0-based indexes!
colName(int)
DEPRECATED. Use column(col).name() instead.
setColName(int,string)
DEPRECATED. Use column(col).setName(name) instead.
setComment(int,string)
DEPRECATED. Use column(col).setComment(text) instead.
setCommand(string or int, string)
Set formula indicated by first argument to the text given in the second argument.
notifyChanges()
DEPRECATED. Update notifications are now done automatically.
importASCII(string, string, int, bool, bool, bool)
importASCII(file, separator="\t", ignored_lines=0, rename_cols=False, strip_spaces=True, simplify_spaces=False) imports file into this table, skipping ignored_lines lines at the beginning and splitting the rest into columns according to the given separator and flags.
exportASCII(string, string, bool, bool)
exportASCII(file, separator="\t", with_comments=False, selection_only=False) exports this table to the given file with the column separator given in the second argument; optionally including column comments and optionally exporting only selected cells.
normalize(string or int)
Normalize specified column to a maximum cell value of one.
normalize()
Normalize all columns in table to a maximum cell value of one.
sortColumn(string or int, int=0)
Sort column indicated in the first argument. The second argument selects the sorting order; 0 means ascending, 1 means descending.
sort(int=0, int=0, string="")
sort(type, order, leading_column) sorts all columns in the table either separately (type=0) or together (type=1) with the leading column given by name. The second argument selects the sorting order; 0 means ascending, 1 means descending.
sortColumns(list of strings, int, int, string)
sortColumns(columns, type=0, order=0, leading_column="") sorts columns given as a tuple of names either separately (type=0) or together (type=1) with the leading column given by name. The third argument selects the sorting order; 0 means ascending, 1 means descending.

class Matrix (inherits MDIWindow)

Class of matrix windows.

mat = newMatrix("mat", 10, 20)
mat.setCoordinates(100,2000,100,1000)
mat.setFormula("i*j")
mat.recalculate()
numRows()
Returns the number of rows in the matrix.
numCols()
Returns the number of columns in the matrix.
setNumRows(int)
Changes the number of rows in the matrix.
setNumCols(int)
Changes the number of columns in the matrix.
setDimensions(int,int)
setDimensions(rows, cols) changes the number of rows and columns simultaneously.
cell(int,int)
cell(row,column) returns the content of the indicated cell as a number.
text(int,int)
text(row,column) returns the content of the indicated cell as its textual representation.
setCell(int,int,double)
setCell(row,column,value) changes the content of the indicated cell to the indicated numeric value.
setText(int,int,string)
setText(row,column,value) interprets the string value according to the numeric format of the matrix and changes the content of the indicated cell accordingly.
xStart()
Returns logical X coordinate of the first column.
xEnd()
Returns logical X coordinate of the last column.
yStart()
Returns logical Y coordinate of the first row.
yEnd()
Returns logical Y coordinate of the last row.
setCoordinates(double,double,double,double)
setCoordinates(x_start, x_end, y_start, y_end) changes the logical coordinate system associated with the matrix.
setFormula(string)
Changes the formula used to (re)calculate cell values of the matrix.
recalculate()
Recalculate all cell values from the currently set formula. Returns boolean indicating success or failure. Added in SciDAVis 0.2.4.
setNumericPrecision(int)
Changes the number of decimal digits being displayed.
transpose()
Mirror matrix at main diagonal (aka matrix transposition).
invert()
Replace the content of the matrix by its inverse (with respect to matrix multiplication).
determinant()
Returns determinant of the matrix.

class ArrowMarker

A line or an arrow displayed on a graph.

arrow = ArrowMarker()
arrow.setStart(50,200)
arrow.setEnd(400,400)
arrow.setWidth(2)
arrow.drawStartArrow(False)
arrow.drawEndArrow(True)
arrow.setColor(Qt.green)

layer = newGraph().activeLayer()
layer.addArrow(arrow)
layer.replot()
ArrowMarker()
Creates a new arrow marker. You can then set various attributes (see below) and hand it to Layer.addArrow().
setStart(double, double)
setStart(x,y) sets the line's start point in plot coordinates (i.e., as displayed on the axes).
setEnd(double,double)
setEnd(x,y) sets the line's end point in plot coordinates (i.e., as displayed on the axes).
setStyle(Qt.PenStyle)
Sets pen style used to draw the line and arrow heads. One of Qt.NoPen, Qt.SolidLine, Qt.DashLine, Qt.DotLine, Qt.DashDotLine, Qt.DashDotDotLine.
setColor(QColor)
Sets the line/arrow head color. Most commonly, the argument will be either a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setWidth(int)
Sets the pen width used to draw line and arrow heads.
drawStartArrow(bool=True)
Sets whether an arrow head is drawn at the line's start.
drawEndArrow(bool=True)
Sets whether an arrow head is drawn at the line's end.
setHeadLength(int)
Sets the length of the arrow heads.
setHeadAngle(int)
Sets the angle defining the "sharpness" of the arrow heads.
fillArrowHead(bool)
Sets whether arrow heads are to be filled out.

class ImageMarker

An image to be displayed on a graph.

layer = newGraph().activeLayer()
image = layer.addImage("/usr/share/icons/hicolor/128x128/apps/scidavis.png")
image.setCoordinates(200,800,700,300)
layer.replot()
ImageMarker(string)
Creates a new image marker displaying the content of the specified image file.
fileName()
Returns the name of the file the image marker refers to.
size()
Returns the size the image takes up in paint (pixel) coordinates as a QSize.
setSize(int,int)
Sets the size the image takes up in paint (pixel) coordinates.
setCoordinates(double,double,double,double)
setCoordinates(left, top, right, bottom) changes position and size of the image marker in plot coordinates.

class Legend

Text boxes displayed on a graph. While this is also used for legends, a better (since more general) name would probably be TextMarker.

layer = newGraph().activeLayer()
legend = layer.newLegend("hello world")
legend.setBackgroundColor(Qt.green)
legend.setTextColor(Qt.darkBlue)
legend.setFont(QtGui.QFont("Arial",14,QtGui.QFont.Bold))
layer.replot()
setText(string)
Changes the legend's content.
setTextColor(QColor)
Changes the text color. Most commonly, the argument will be either a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setFrameStyle(int)
Sets the style of frame drawn around the text. 0 for none, 1 for line or 2 for line with shadow.
setBackgroundColor(QColor)
Changes the background color. Most commonly, the argument will be either a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setFont(QFont)
Sets the font used to render the text. See QFont documentation for how to construct a valid argument.
setOriginCoord(double,double)
setOriginCoord(x,y) sets the position of the top-left corner in plot coordinates.

class QwtSymbol

Represents a type of symbol on a scatter plot (ellipse, rectangle etc.) together with attributes determining parameters like color, size etc. This class is part of the Qwt library, but exported and documented as part of SciDAVis's API for simplicity. Also, convenience methods for setting outline/fill colors are added on top of Qwt.

symbol = QwtSymbol()
symbol.setStyle(QwtSymbol.Triangle)
symbol.setOutlineColor(QtGui.QColor(Qt.red))
symbol.setFillColor(QtGui.QColor(Qt.green))
symbol.setSize(20)
# assuming Graph1 exists and contains a plot
layer = graph("Graph1").activeLayer()
layer.curve(0).setSymbol(symbol)
layer.replot()
QwtSymbol()
Construct new symbol with default settings (= no symbol).
QwtSymbol(Style, QBrush, QPen, QSize)
Construct new symbol, with the four properties set as if given to setStyle(), setBrush(), setPen() and setSize(), respectively.
setColor(QColor)
Simultaneously sets color for filling and drawing the outline. Modifies pen() and brush(). Note that due to the setColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setColor(int)
Convenience overload of setColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
setOutlineColor(QColor)
Sets the color used for drawing the outline of the symbol. Modifies pen(). Note that due to the setOutlineColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setOutlineColor(int)
Convenience overload of setOutlineColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
setFillColor(QColor)
Sets the color used for filling the interior of the symbol. Modifies brush(). Note that due to the setFillColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setFillColor(int)
Convenience overload of setFillColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
clone()
Returns an independent copy of the symbol object.
setSize(QSize)
Sets size of the symbol in paint (pixel) coordinates.
setSize(int,int=-1)
setSize(width,height) sets the size of the symbol in paint (pixel) coordinates. If height=-1 (default), it is set to equal to width.
setBrush(QBrush)
Sets the brush used to fill the interior of the symbol. See PyQt documentation for how to construct a QBrush.
setPen(QPen)
Sets the pen used to draw the border of the symbol. See PyQt documentation for how to construct a QPen.
setStyle(Style)
Sets the type of symbol to draw. The argument needs to be one of the integer constants QwtSymbol.NoSymbol, QwtSymbol.Ellipse, QwtSymbol.Rect, QwtSymbol.Diamond, QwtSymbol.Triangle, QwtSymbol.DTriangle, QwtSymbol.UTriangle, QwtSymbol.LTriangle, QwtSymbol.RTriangle, QwtSymbol.Cross, QwtSymbol.XCross, QwtSymbol.HLine, QwtSymbol.VLine, QwtSymbol.Star1, QwtSymbol.Star2, QwtSymbol.Hexagon.
brush()
Returns the currently set brush (a QBrush) for filling the interior of the symbol. Due to a design limitation of Qwt, setting attributes of the brush directly has no effect. You need to create a copy of the brush, change its attributes and hand it again to setBrush().
pen()
Returns the currently set pen (a QPen) for drawing the border of the symbol. Due to a design limitation of Qwt, setting attributes of the pen directly has no effect. You need to create a copy of the pen, change its attributes and hand it again to setPen().
size()
Returns the currently set size (a QSize) in paint (pixel) coordinates for drawing the symbol. Due to a design limitation of Qwt, setting attributes of the QSize directly has no effect. You need to create a copy of the size, change its attributes and hand it again to setSize().
style()
Returns an integer denoting the currently set type of symbol. See setStyle() for possible values.

class QwtPlotCurve

Represents a curve with symbols and/or lines on a graph. This class is part of the Qwt library, but exported and documented as part of SciDAVis's API for simplicity. Also, convenience methods for setting outline/fill colors and fill style are added on top of Qwt.

# assuming Graph1 exists and contains a lines plot
layer = graph("Graph1").activeLayer()
curve = layer.curve(0)
curve.setOutlineColor(QtGui.QColor(Qt.red))
curve.setFillColor(QtGui.QColor(Qt.green))
curve.setFillStyle(Qt.CrossPattern)
layer.replot()
dataSize()
Returns the number of points in the curve.
x(int)
Returns X coordinate of indicated point.
y(int)
Returns Y coordinate of indicated point.
minXValue()
Return smallest X value of the curve's points.
maxXValue()
Return largest X value of the curve's points.
minYValue()
Return smallest Y value of the curve's points.
maxYValue()
Return largest Y value of the curve's points.
setXAxis(x-axis)
Set the x-axis to which the curve is attached. x-axis is Layer.Bottom or Layer.Top.See also: setCurveAxes.
setYAxis(y-axis)
Set the x-axis to which the curve is attached. y-axis is Layer.Left or Layer.Right.See also: setCurveAxes.
setPen(QPen)
Sets the pen used to draw the lines of the curve. See PyQt documentation for how to construct a QPen.
pen()
Returns the currently set pen (a QPen) for drawing the lines of the curve. Due to a design limitation of Qwt, setting attributes of the pen directly has no effect. You need to create a copy of the pen, change its attributes and hand it again to setPen().
setBrush(QBrush)
Sets the brush used to fill the area under the curve. See PyQt documentation for how to construct a QBrush.
brush()
Returns the currently set brush (a QBrush) for filling the area under the curve. Due to a design limitation of Qwt, setting attributes of the brush directly has no effect. You need to create a copy of the brush, change its attributes and hand it again to setBrush().
setSymbol(QwtSymbol)
Specifies whether and how symbols are drawn. See class QwtSymbol.
symbol()
Returns symbol parameters currently in effect. See class QwtSymbol. Due to a design limitation of Qwt, setting attributes of the symbol directly has no effect. You need to create a copy of the symbol, change its attributes and hand it again to setSymbol().
setColor(QColor)
Simultaneously sets color for drawing lines and filling the area under the curve. Modifies pen() and brush(). Note that due to the setColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setColor(int)
Convenience overload of setColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
setOutlineColor(QColor)
Sets the color used for drawing the lines of the curve. Modifies pen(). Note that due to the setOutlineColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setOutlineColor(int)
Convenience overload of setOutlineColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
setFillColor(QColor)
Sets the color used for filling the area under the curve. Modifies brush(). Note that due to the setFillColor(int) overload, and unlike other methods accepting QColor arguments, basic colors need to be explicitly specified as QtGui.QColor(Qt.white) etc. instead of just Qt.white. As usual, it's also possible to give an RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setFillColor(int)
Convenience overload of setFillColor(QColor) choosing the color to be set from the palette used by SciDAVis for automatically assigning colors to new curves.
setFillStyle(Qt.BrushStyle)
Set pattern used for filling the area under the curve. Argument must be one of Qt.SolidPattern, Qt.Dense1Pattern, Qt.Dense2Pattern, Qt.Dense3Pattern, Qt.Dense4Pattern, Qt.Dense5Pattern, Qt.Dense6Pattern, Qt.Dense7Pattern, Qt.NoBrush, Qt.HorPattern, Qt.VerPattern, Qt.CrossPattern, Qt.BDiagPattern, Qt.FDiagPattern, Qt.DiagCrossPattern, Qt.LinearGradientPattern, Qt.RadialGradientPattern, Qt.ConicalGradientPattern. See PyQt documentation for visual overview and more information.

class Grid

Handles options related to the grid drawn on a Layer. Added in SciDAVis 0.2.4.

layer = newGraph().activeLayer()
layer.showGrid()
layer.grid().setMajorPen(QtGui.QColor(Qt.black))
layer.replot()
setMajor(bool)
Enables/disables drawing of major grid lines for both axes.
setXMajor(bool)
Enables/disables drawing of major grid lines for X axis.
setYMajor(bool)
Enables/disables drawing of major grid lines for Y axis.
xMajor()
Boolean indicating whether major grid lines for X axis are enabled.
yMajor()
Boolean indicating whether major grid lines for Y axis are enabled.
setMinor(bool)
Enables/disables drawing of minor grid lines for both axes.
setXMinor(bool)
Enables/disables drawing of minor grid lines for X axis.
setYMinor(bool)
Enables/disables drawing of minor grid lines for Y axis.
xMinor()
Boolean indicating whether minor grid lines for X axis are enabled.
yMinor()
Boolean indicating whether minor grid lines for Y axis are enabled.
setXZeroLine(bool)
Enables/disables drawing of line at X=0.
xZeroLine()
Boolean indicating whether a line is drawn at X=0.
setYZeroLine(bool)
Enables/disables drawing of line at Y=0.
yZeroLine()
Boolean indicating whether a line is drawn at Y=0.
setMajorPen(QPen)
Sets color, line width, line style etc. of major grid lines. See PyQt reference for class QPen.
setXMajorPen(QPen)
Sets color, line width, line style etc. of major grid lines for X axis. See PyQt reference for class QPen.
setYMajorPen(QPen)
Sets color, line width, line style etc. of major grid lines for Y axis. See PyQt reference for class QPen.
xMajorPen()
Returns QPen used for drawing major grid lines for X axis. See PyQt reference for class QPen.
yMajorPen()
Returns QPen used for drawing major grid lines for Y axis. See PyQt reference for class QPen.
setMinorPen(QPen)
Sets color, line width, line style etc. of minor grid lines. See PyQt reference for class QPen.
setXMinorPen(QPen)
Sets color, line width, line style etc. of minor grid lines for X axis. See PyQt reference for class QPen.
setYMinorPen(QPen)
Sets color, line width, line style etc. of minor grid lines for Y axis. See PyQt reference for class QPen.
xMinorPen()
Returns QPen used for drawing minor grid lines for X axis. See PyQt reference for class QPen.
yMinorPen()
Returns QPen used for drawing minor grid lines for Y axis. See PyQt reference for class QPen.

class Layer (inherits QWidget)

A layer on a graph. All elements in a graph are organized in layers, so whenever you're working with graphs, you're also dealing with layers. Note that many changes do not show up until you call replot() - if you're changing many options on a complex layer, this is faster than automatically updating the layer on every change.

layer = newGraph().activeLayer()
layer.setTitle("Murphy Certainty Principle")
layer.setXTitle("time")
layer.setYTitle("motivation")
layer.insertFunctionCurve("1/x", 0, 10)
# the constants QwtPlot.xBottom (=2) and QwtPlot.yLeft (=0) were added in SciDAVis 0.2.4
layer.setScale(QwtPlot.xBottom, 0, 10)
layer.setScale(QwtPlot.yLeft, 0, 10)
layer.setBackgroundColor(QtGui.QColor(18,161,0))
layer.setCanvasColor(QtGui.QColor(161,120,50))
layer.curve(0).setPen(QtGui.QPen(Qt.yellow, 3))
layer.removeLegend()
layer.replot()
isPiePlot()
Boolean indicating whether this layer is a pie plot. Pie plots are always on a separate layer.
pieLegend()
Returns content of legend, assuming this layer is a pie plot. See isPiePlot().
insertCurve(Table, string, int, int)
insertCurve(table, column, style=1, color=-1) plots the data of the specified Y column and the corresponding designated X column, optionally specifying style and color, and returning a boolean indicating success or failure. Color is an index in the palette used by SciDAVis for automatically assigning colors to new curves. Style is one of the following codes:
0
Line
1
Symbols
2
Line and Symbols
3
Columns
4
Area
5
Pie
6
Vertical drop lines
7
Splines and Symbols
8
Vertical steps
9
Histogram
10
Rows
insertCurve(Table, string, string int, int)
insertCurve(table, x_column, y_column style=1, color=-1) works like the other insertCurve() variant above, but allows you to explicitly specify the X column you want to plot against instead of determining it by designation.
insertFunctionCurve(string, double=0, double=1, int=100, string=QtCore.QString())
insertFunctionCurve(formula, start, end, points, title) inserts a function curve specified by formula, which is evaluated using muParser with abscissa "x", and returns a boolean indicating success or failure. Optionally, the interval [start,end] for the evaluation, the number of points where the function will be evaluated and the curve title can be given. Added in SciDAVis 0.2.4.
insertPolarCurve(string, string, double=0, double=2*pi, string="t", int=100, string=QtCore.QString())
insertPolarCurve(radial, angular, start, end, parameter, points, title) inserts a function curve specified by formulas for the radial and angular components in polar coordinates, both of which are evaluated using muParser with given parameter ("t" by default), and returns a boolean indicating success or failure. Optionally, the interval [start,end] covered by the free parameter, the number of points where the function will be evaluated and the curve title can be overridden. Added in SciDAVis 0.2.4.
insertParametricCurve(string, string, double=0, double=1, string="t", int=100, string=QtCore.QString())
insertParametricCurve(x_formula, y_formula, from, to, parameter, points, title) insert a function curve specified by formulas for the abscissa and ordinate components in cartesian coordinates, both of which are evaluated using muParser with given parameter ("t" by default), and returns a boolean indicating success or failure. Optionally, the interval [start,end] covered by the free parameter, the number of points where the function will be evaluated and the curve title can be overridden. Added in SciDAVis 0.2.4.
addErrorBars(string, Table, string, int=1, int=1, int=8, QColor=QColor(Qt.black), bool=True, bool=True, bool=True)
addErrorBars(curve, table, err_col_name, orientation, width, cap_length, color, through, minus, plus) adds error bars to the curve specified by its name (as displayed in the add/remove curve dialog and the curves' context menu). Data for the error bars is taken from the given table and column. Optionally, you can override the orientation (default is 1 for vertical, 0 means horizontal), the width of the pen used to draw the error bars, the length of the caps in pixels, the color of the pen used to draw the error bars, and flags indicating whether the error bars' line strikes through the underlying curve, and whether the minus and plus side of the error bars are to be drawn.
removeCurve(int or string)
Remove curve specified by index (in the range [0,numCurves()-1]) or title.
deleteFitCurves()
Remove all curves that show the result of a fit operation.
numCurves()
Returns the number of curves plotted on this layer.
showCurve(int,bool)
Show/hide the curve specified by its index (in the range [0,numCurves()-1]). Hidden curves are not plotted, but otherwise remain part of the Layer; they keep their legend item, count as part of numCurves(), can be accessed by curve() etc.
curve(int or string)
Access curve (as QwtPlotCurve instance) specified by its title (as displayed in the add/remove curves dialog and the curve's context menu) or index (integer in the range [0,numCurves()-1].
curves()
Returns a list of all curves in the layer. Added in SciDAVis 0.2.4.
addArrow(ArrowMarker)
Add the indicated arrow/line marker to the layer. See class ArrowMarker.
addImage(ImageMarker or string)
Add an image marker to the layer. For convenience, you can simply specify the path of the file containing the image in place of an ImageMarker object. In any case, the added ImageMarker is returned.
setTitle(string)
Change the layer's title string.
newLegend()
Return a new, empty Legend (text marker) object after adding it to this layer.
newLegend(string)
Return a new Legend (text marker) object initialized with the given string, after adding it to the layer.
setLegend(string)
Set the name of the main legend (i.e., the real legend, as opposed to other texts placed on the layer).
legend()
Returns the Legend object representing the real legend, as opposed to other texts placed on the layer.
removeLegend()
Remove the legend (i.e., the object returned by legend()), if one currently exists.
addTimeStamp
Add a text marker containing the current date and time.
enableAxis(int,bool)
Enable/disable drawing of the indicating axis, which must be one of the integer constants QwtPlot.yLeft (=0), QwtPlot.yRight (=1), QwtPlot.xBottom (=2) or QwtPlot.xTop (=3). The descriptive names were added in SciDAVis 0.2.4; for prior versions, you need to specify the indicated integer values.
setXTitle(string)
Set the title displayed for the (bottom) X axis. The axis title can be disabled by setting it to an empty string.
setYTitle(string)
Set the title displayed for the (left) Y axis. The axis title can be disabled by setting it to an empty string.
setRightTitle(string)
Set the title displayed for the right Y axis. The axis title can be disabled by setting it to an empty string. Added in SciDAVis 0.2.4.
setTopTitle(string)
Set the title displayed for the top X axis. The axis title can be disabled by setting it to an empty string. Added in SciDAVis 0.2.4.
setAxisNumericFormat(int, int, int=6, string=QString())
setAxisNumericFormat(axis, format, precision, formula) sets the numeric format used for drawing the axis labels on the specified axis (see enableAxis() for possible arguments). Format must be one of 0 (automatic), 1 (decimal), 2 (scientific) or 3 (superscripts). Precision is the number of digits displayed. If a formula is given, it is evaluated with muParser for every label and the result is used in place of the input value for displaying the label.
setScale(int, double, double, double=0, int=5, int=5, int=0, bool=False)
setScale(axis, start, end, step, major_ticks, minor_ticks, type, inverted) sets various options related to the scale of the indicated axis (see enableAxis() for possible arguments); most notably the start and end values of the displayed data range. Step indicates the distance between major tick marks (the default of 0 means to automatically determine a sensible value); alternatively, a target number of major tick marks (and minor tick marks per major tick) can be specified, but due to limitations of Qwt, this is only taken as a hint, not as a strictly followed setting. Type is either 0 (linear scale, default) or 1 (logarithmic scale). The last flag can be set to have the axis inverted, i.e. numbered right to left or top-down.
setMargin(int)
Change the margin (i.e., the spacing around the complete content) of the layer.
setFrame(int=1, QColor=QColor(Qt.black))
setFrame(width, color) draws a frame around the complete content (including margin) of the layer; with the indicated line width and color.
setBackgroundColor(QColor)
Changes the background color of the layer. Note that this excludes the background of the canvas area containing the curves and markers, which is set separately (see setCanvasColor()). Most commonly, the argument will be either a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
setCanvasColor(QColor)
Changes the background color of the canvas area containing the curves and markers. Most commonly, the argument will be either a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range [0,255] (see QColor for details).
showGrid(int)
Toggle drawing of major and minor grid associated with the given axis. See enableAxis() for possible arguments.
showGrid()
Toggle drawing of all grid lines.
grid()
Returns the Grid object for this layer, which holds various grid-related settings. See class Grid. Added in SciDAVis 0.2.4.
replot()
Makes sure that any changes you've applied to the layer are displayed on screen. It is often necessary to call this method after making script-driven changes to a layer, like changing the style of a curve. It is also a good idea to call this before export to a file, although it's not technically required for all file formats.
printDialog()
Display dialog for printing out this layer. Added in SciDAVis 0.2.4.
exportImage(string, int=100, bool=False)
exportImage(filename, quality, transparent) exports the layer to a bitmap image format with the indicated quality level, optionally making the background transparent (if supported by the file format). The file format is determined by the extension of the indicated file name; the list of supported formats depends on your installation of Qt and can be viewed by invoking the export dialog from the GUI and looking through the "file type" box.
exportVector(string, int=0, bool=True, bool=True, QPrinter.PageSize=QtGui.QPrinter.Custom)
exportVector(filename, resolution, color, keep_aspect, page_size) exports the layer to a vector-based file format. You can override the default resolution (in dpi), toggle printing in color/monochrome, toggle whether to keep the width/height aspect when rescaling and select a standard page size as described in the PyQt documentation for QtGui.QPrinter.PageSize.
export(string)
Quickly export layer to the indicated file, without bothering about the exportImage()/exportVector() distinction and related options. The file format is determined automatically by looking at the extension of the specified file name; supported formats depend on your installation of Qt and can be viewed by invoking the export dialog from the GUI and looking through the "file type" box.
enableAutoscaling(bool=True)
Set automatic updating of the scale settings (see setScale()) when data is added to or changed on the layer.
setIgnoreResize(bool=True)
Sets whether to keep the layer's geometry fixed when resizing its graph.
setAutoscaleFonts(bool=True)
Sets whether to scale font sizes together with the rest of the layer when its graph is resized (and resizes aren't ignored, see setIgnoreResize()).
setAntialiasing(bool=True, bool=True)
setAntialiasing(antialias, update) specifies whether antialiasing should be used for drawing elements added to the layer after the call to setAntialiasing(). If the update flag is True (default), the antialiasing setting of existing elements is updated as well.
setCurveAxes(number, x-axis, y-axis)
Note: when using this method the involved axes are autoscaled.See also: setXAxis, setYAxis
canvas()
Gives access to the QtGui.QWidget acting as a canvas, i.e it contains all curves and markers on the layer (but not axes and title).
pickPoint()
Let the user pick a point on a curve (as with the Data Reader tool) and return the coordinates of the selected point as a QPointF (coordinates can be extracted from the result using QPointF.x() and QPointF.y()). Added in SciDAVis 0.2.4.

class Graph (inherits MDIWindow)

A graph window, consisting of layers, which in turn contain plot curves and markers. 

g = newGraph()
layer1 = g.activeLayer()
layer2 = g.addLayer()
g.setMargins(40,40,40,40)
g.arrangeLayers()
activeLayer()
Returns the Layer currently marked as active (as indicated by the layer buttons at the top of the graph). If there is only one layer, it is always the active one.
setActiveLayer(Layer)
Make the indicated layer the active one.
numLayers()
Returns the total number of layers contained in the graph.
layer(int)
Returns the Layer specified by index (integer in the range [1,numLayers()]).
layers()
Returns a list of all layers in the graph. Added in SciDAVis 0.2.4.
addLayer(int=0,int=0,int=0,int=0)
addLayer(x,y,width,height) adds a new layer at the given position and with the given size. Returns the newly created Layer object.
setCols(int)
Set the number of columns to use when arranging layers automatically. Doesn't take effect until a re-arrangement is requested by calling arrangeLayers().
setRows(int)
Set the number of rows to use when arranging layers automatically. Doesn't take effect until a re-arrangement is requested by calling arrangeLayers().
setSpacing(int,int)
setSpacing(row_gap, column_gap) sets the spacing to use between rows and columns when arranging layers automatically. Doesn't take effect until a re-arrangement is requested by calling arrangeLayers().
setMargins(int,int,int,int)
setMargins(left,right,top,bottom) sets the outer margins to use when arranging layers automatically. Doesn't take effect until a re-arrangement is requested by calling arrangeLayers().
setLayerCanvasSize(int, int)
setLayerCanvasSize(width,height) Resizes all layers as indicated and arranges them automatically.
setAlignment(int, int)
setAlignment(horizontal, vertical) sets the alignement of layers in their respective columns and rows. Arguments can be 0 For center, 1 for left/top and 2 for right/bottom. Added in SciDAVis 0.2.4.
arrangeLayers(bool)
Automatically arranges the layers on the graph, subject to built-in defaults or settings made previously using setCols(), setRows(), setSpacing(), setMargins() and setAlignment().
exportImage(string, int=100, bool=False)
exportImage(filename, quality, transparent) exports the graph to a bitmap image format with the indicated quality level, optionally making the background transparent (if supported by the file format). The file format is determined by the extension of the indicated file name; the list of supported formats depends on your installation of Qt and can be viewed by invoking the export dialog from the GUI and looking through the "file type" box.
exportVector(string, int=0, bool=True, bool=True, QPrinter.PageSize=QtGui.QPrinter.Custom)
exportVector(filename, resolution, color, keep_aspect, page_size) exports the graph to a vector-based file format. You can override the default resolution (in dpi), toggle printing in color/monochrome, toggle whether to keep the width/height aspect when rescaling and select a standard page size as described in the PyQt documentation for QtGui.QPrinter.PageSize.
export(string)
Quickly export graph to the indicated file, without bothering about the exportImage()/exportVector() distinction and related options. The file format is determined automatically by looking at the extension of the specified file name; supported formats depend on your installation of Qt and can be viewed by invoking the export dialog from the GUI and looking through the "file type" box.
printDialog()
Display dialog for printing out this layer. Added in SciDAVis 0.2.4.

class Note (inherits MDIWidget)

A note/script window containing arbitrary text, all or parts of which can be executed as Python code. Triggering executing of code in a Note currently doesn't work reliably, but this can essentially be circumvented using exec(str(note.text())).

n = newNote()
n.setText("Hello World")
n.exportASCII("output.txt")
autoexec()
Boolean indicating whether the content of Note is automatically executed when loading the project.
setAutoexec(bool)
Sets whether to automatically executed the content of the Note when loading the project.
text()
Returns the content of the note as a QString.
setText(string)
Sets the content of the note.
exportASCII(string)
Writes the content of the note to the indicated file.
importASCII(string)
Prepends the content of the note by the content of the indicated file.

class ApplicationWindow (inherits QMainWindow)

Manages the current project. The project from which a piece of Python code is executed is accessible via the module attribute scidavis.app. However, most of the time, this instance is used implicitly via methods copied to the global namespace by the default scidavisrc.py configuration file.

for win in app.windows():
	print win.name()
app.activeFolder().save("subproject.sciprj")
table(string)
Returns the table with the given name, or None if no such table exists.
newTable()
Creates a new table with default settings (as if done using the menu) and returns it.
newTable(string, int=2, int=30)
newTable(name, columns, rows) creates a new table with the given name and (optionally) numbers of columns and rows, and returns it. If the specified name is already in use, it is changed automatically to a unique name by appending a number to the requested name.
matrix(string)
Returns the matrix with the given name, or None if no such matrix exists.
newMatrix()
Creates a new matrix with default settings (as if done using the menu) and returns it.
newMatrix(string, int=32, int=32)
newMatrix(name, rows, columns) creates a new matrix with the given name and (optionally) numbers of columns and rows, and returns it. If the specified name is already in use, it is changed automatically to a unique name by appending a number to the requested name.
graph(string)
Returns the graph with the given name, or None if no such graph exists.
newGraph()
Creates a new graph containing one empty layer (as if done using the menu) and returns it.
newGraph(string)
newGraph(name) creates a new graph with the given name containing one empty layer (as if done using the menu) and returns it. If the specified name is already in use, it is changed automatically to a unique name by appending a number to the requsted name. Added in SciDAVis 0.2.4.
note(string)
Returns the note window with the given name, or None if no such note exists.
newNote()
Creates a new empty note and returns it.
newNote(string)
newNote(name) creates a new empty note with the given name and returns it. If the specified name is already in use, it is changed automatically to a unique name by generating a default name like "Notes1". This is inconsistent with newTable(), newMatrix and newGraph() (which generate a unique name by appending a number to the requested name) and will probably change in a future release.
plot(Table, string, int=1, int=-1)
plot(table, column, style, color) plots the named column of the given table. A new graph is created containing one layer, to which the curve is added. The new graph is returned. Optionally, style and color of the curve can be set, where color is an index in the palette used by SciDAVis for automatically assigning colors to new curves and style is one of the following codes:
0
Line
1
Symbols
2
Line and Symbols
3
Columns
4
Area
5
Pie
6
Vertical drop lines
7
Splines and Symbols
8
Vertical steps
9
Histogram
10
Rows
plot(Table, tuple of strings, int=1, int=-1)
plot(table, (column1, column2, ...), style, color) works just like the plot method described above, but plots multiple columns together on the same layer.
importImage(string)
Reads an image from the specified file and returns a newly created matrix containing the gray-scale values (brightness) of the image's pixels.
importImage()
Ask the user to select an image file and imports it to a newly created matrix as described above. Returns the matrix.
plotContour(Matrix)
Makes a contour plot from the given matrix in a newly created graph. Returns the graph.
plotColorMap(Matrix)
Makes a contour plot from the given matrix, filling contour areas with colors of the default color map. Returns the newly created graph.
plotGrayScale(Matrix)
Makes a gray scale plot from the given matrix in a newly created graph. Returns the graph.
windows()
Returns a list of all MDIWindow instances in the project.
results
The QTextEdit which holds the results log. Can be used to output custom results from your script, although the recommended way of doing this is to create a Note and set its text to what you want to output.
activeFolder()
Returns the folder which is currently being displayed.
setActiveFolder(folder)
Given a Folder object, changes the active folder to it. Since MDIWindows are always added to the active folder, this is necessary for script-driven creation of objects in specific sub-folders. Added in SciDAVis 0.2.5.
rootFolder()
Returns the root folder of the project.
saveFolder(Folder, string)
DEPRECATED. SciDAVis 0.2.4 introduces the new method Folder.save(), which is the recommended way of saving folders to a new project file; unless you need the code to run on previous versions.
renameWindow(MDIWindow, string)
DEPRECATED. SciDAVis 0.2.4 introduces the new method MDIWindow.setName(), which is the recommended way of renaming windows; unless you need the code to run on previous versions.
clone(MDIWindow)
DEPRECATED. SciDAVis 0.2.4 introduces the new method MDIWindow.clone(), which is the recommended way of cloning windows; unless you need the code to run on previous versions.
setPreferences(Layer)
DEPRECATED. Prior to SciDAVis 0.2.4, it was necessary to call this on a layer created using Graph.addLayer() if you wanted the layer to be initialized correctly. This is now done automatically as part of addLayer(); doing so again doesn't hurt, but is not necessary any more.

class Fit (inherits QObject)

This is the abstract base class of the various models that can be used for least-squares parameter fitting; in other words, you can only create instances of subclasses of this class, but the methods described here are common to all of these classes (ExponentialFit, SigmoidalFit etc.).
Fit(ApplicationWindow, Layer, string)
Constructor, taking the ApplicationWindow instance to which the Fit will belong, the Layer containing data to be fitted (and receiving the result curve) and a name for the fitter. Mainly interesting if you want to implement a custom fitter as a subclass of Fit.
fit()
Executes the fit (after setting data and parameters). Must be reimplemented by subclasses.
setYErrorSource(ErrorSource, string="")
Specify the standard errors of the Y values (compare setDataFromCurve()). ErrorSource is one of Fit.UnknownErrors (no weighting is done and errors are estimated from the variance of the input values), Fit.AssociatedErrors (the yErr column associated with the source column is used), Fit.PoissonErrors (input values are Poisson distributed, i.e. errors are equal to the square root of the values) or Fit.CustomErrors (the name of the column containing the errors is given as the second parameter).
setDataFromCurve(string, Layer)
Use the curve (given by name) on the given layer as the fit data. Returns a boolean indicating success (True) or failure (False).
setDataFromCurve(string, double, double, Layer)
DEPRECATED. Use the variant above followed by setInterval() instead.
setInterval(double, double)
setInterval(from,to) restricts the X interval of the data points included in the fit to [from,to].
formula()
Returns the formula of the fit model (in a format suitable for evaluation with muParser).
numParameters()
Returns the number of free parameters in the fit.
setInitialValue(int, double)
setInitialValue(index, value) specifies the initial value for the parameter given by index.
setInitialValues(sequence)
Set initial values of all parameters at once.
guessInitialValues()
Try to determine sensible initial values for the parameters automatically. Can be reimplemented by subclasses if they want to support this feature; currently, only SigmoidalFit and MultiPeakFit can do this trick.
setAlgorithm(Algorithm)
Set the fitting algorithm; one of Fit.ScaledLevenbergMarquardt, Fit.UnscaledLevenbergMarquardt or Fit.NelderMeadSimplex.
setTolerance(double)
Set the tolerance up to which the result has to be determined. The Fit algorithm is iterated until either the desired tolerance or the maximum number of iterations (see setMaximumIterations()) is reached; in the latter case, it aborts with a failure notice.
setColor(int)
Set the color of the generated fit curve from the palette used by SciDAVis for automatically assigning colors to new curves. (Specifying a color by name is DEPRECATED, because its counter-intuitive behaviour was more likely to cause trouble than to make things easier.)
setOutputPrecision(int)
Set the number of decimal places to use when formatting numbers for output to the results log or to a graph.
generateFunction(bool, int=100)
By default, fit results are pasted into the target graph layer as a function curve. Calling generateFunction(False, num_points) causes the fit results to be written into a hidden table (with num_points data points) and plotted from there. This may be useful if you want to use fit results for further calculations.
setMaximumIterations(int)
Sets the maximum number of times to iterate the fitting algorithm before giving up and declaring the fit to have failed.
showLegend()
Insert information on the fit into the target graph layer.
legendInfo()
Return the information inserted by showLegend() as a string. Can be overridden by subclasses in order to customize it.
scaleErrors(bool)
Set flag indicating whether to multiply standard errors of final parameters by χ2/(degrees of freedom). Defaults to False.
results()
Returns the final parameters as a tuple of floats.
errors()
Returns standard errors of final parameters as a tuple of floats.
chiSquare()
Returns the sum of squares of the residuals from the best-fit line.
rSquare()
Returns the coefficient of determination of the best-fit line.
parametersTable(string)
Creates a Table with the given name and fills it with the final parameter values. Returns a reference to the Table window.
covarianceMatrix(string)
Creates a Matrix with the given name and fills it with the covariance matrix of the final parameter values. Returns a reference to the Matrix window.

class Folder (inherits QObject)

Folder(name)
Construct a new folder with the given name. You can add it as a subfolder to an existing one using addChild() (see below).
windows()
Returns the list of MDIWindows contained in this folder.
name()
Returns the name of this folder (a string).
path()
Returns the absolute path of this folder within its project (a string).
folders()
Returns the list of sub-folders.
folder(string, bool=True, bool=False)
folder(name, case_sensitive, partial_match) returns the first subfolder matching the given name. A subfolders is considered to match if its name equals the name argument; if partial_match is True, it is also considered to match if its name starts with the name argument. Matching can be made case-insensitive by setting the case_sensitive argument to False.
findWindow(string, bool=True, bool=True, bool=False, bool=True)
findWindow(str, match_name, match_label, case_sensitive, partial_match) returns the first MDI window whose name (if match_name is True) or label (if match_label is True) matches the given string. A name or label is considered to match if it equals the string argument; if partial_match is True, it is also considered to match if its name starts with the name argument. Matching can be made case-sensitive by setting the case_sensitive argument to True.
table(string, bool=False)
table(name, recursive) returns the table of the given name in this folder; if no such table exists and recursive is True, sub-folders are searched as well.
matrix(string, bool=False)
matrix(name, recursive) returns the matrix of the given name in this folder; if no such matrix exists and recursive is True, sub-folders are searched as well.
graph(string, bool=False)
graph(name, recursive) returns the graph of the given name in this folder; if no such graph exists and recursive is True, sub-folders are searched as well.
note(string, bool=False)
note(name, recursive) returns the note of the given name in this folder; if no such note exists and recursive is True, sub-folders are searched as well.
rootFolder()
Returns the root folder of the project this folder belongs to.
save(string)>
Given a file name, saves the content of this folder as a project file. Added in SciDAVis 0.2.4.
addChild(folder)
Adds another folder as a sub-folders to this one. Added in SciDAVis 0.2.5.

The Initialization File

This file allows you to customize the Python environment, import modules and define functions and classes that will be available in all of your projects. The default initialization file shipped with SciDAVis imports Python's standard math functions as well as special functions from SciPy and PyGSL(if available). Also, it creates some handy shortcuts, like table("table1") for sci.app.table("table1").

When activating Python support, SciDAVis searches the following places, executing the first file it can find:

  1. ~/.scidavisrc.py[c]

  2. /etc/scidavisrc.py[c]

  3. ./scidavisrc.py[c]

Files ending in .pyc are compiled versions of the .py source files and therefore load a bit faster. The compiled version will be used if the source file is older or nonexistent. Otherwise, SciDAVis will try to compile the source file (if you've got write permissions for the output file).

Recommended approach to per-user configuration

In order to give you full control over the process of setting up the Python environment within SciDAVis, a per-user configuration file (.scidavisrc.py) will supersede any system-wide configuration file. That is, GSL and SciPy functions as well as many SciDAVis-specific functions (like table(), newTable(), plot(), etc.) will be missing, unless you explicitly import them into the global namespace. In order to keep the overview over their customizations and profit from updates to the global configuration files (e.g. with new versions of SciDAVis), most users will want to import the global configuration file from within their custom one. Here's how to do this: 

import sys 
sys.path.append("/etc") 
import scidavisrc 
# your custom stuff
Prev  Up  Next
Chapter 4. Scripting  Home  Chapter 5. Command Reference