Python

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

The Initialization File

The qtiplotrc.py file allows you to customize the Python environment, import modules and define functions and classes that will be available in all of your projects. If QtiPlot was built using Qt 4 library, the name of the default initialization file is qtiplotrc_qt4.py.

The default initialization file shipped with QtiPlot imports Python's standard math functions as well as (if available) special functions from SciPy, the symbolic mathematics library SymPy and helper functions for RPy2. Also, it creates some handy shortcuts, like table("table1") for qti.app.table("table1").

When activating Python support, QtiPlot searches the initialization file in a default folder, which can be customized via the File Locations tab of the Preferences dialog. If the initialization file is not found, QtiPlot will issue a warning and muParser will be kept as the default interpreter.

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, QtiPlot will try to compile the source file (if you've got write permissions for the output file).

Python Basics

Mathematical expressions work largely as expected. However, there's one caveat, especially when switching from muParser (which has been used exclusively in previous versions of QtiPlot): 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

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,


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. All statements outside of any function use module scope; that is, variables attached to one column script or script window. All statements inside a function use that function's "local" scope, but they can also read module variables. System-wide globals are stored in the special variable globals. To store your own:

globals.mydata = 5
print globals.mydata
	  
Global scope rules recently changed In older versions, write this instead:

global mydata
mydata = 5
print mydata
	  

Defining Functions and Control Flow

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 other modules, you have to add it to the globals:

def answer():
	return 42
globals.answer = answer
	
If you have an older versions of QtiPlot, you have to declare it global before the definition:

global answer
def answer():
	return 42
	
You can add your own function to QtiPlot's function list. We'll also provide a documentation string that will show up, for example, in the "set column values" dialog:

def answer():
	"Return the answer to the ultimate question about life, the universe and everything."
	return 42
qti.mathFunctions["answer"] = answer
	
If you want to remove a function from the list, do:

del qti.mathFunctions["answer"]
	

Global scope rules recently changed In older versions, a function's local scope hid the module scope. That means that if you entered a function definition in a Note, you would not be able to access (neither reading nor writing) Note-local variables from within the function. However, you could 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).

Mathematical Functions

Python comes with some basic mathematical functions that are automatically imported (if you use the initialization file shipped with QtiPlot). Along with them, the constants e (Euler's number) and pi (the one and only) are defined.

Table 7-5. Python: Supported Mathematical Functions

NameDescription
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 QtiPlot's objects from Python

We will assume that you are using the initialization file shipped with QtiPlot. Accessing the objects in your project is straight-forward,


t = table("Table1")
m = matrix("Matrix1")
g = graph("Graph1")
p = plot3D("Graph2")
n = note("Notes1")
# get a pointer to the QTextEdit object used to display information in the results log window:
log = resultsLog()
# display some information in the data display toolbar:
displayInfo(text)
# get a pointer to the QLineEdit object in the data display toolbar and access the information displayed:
info = infoLineEdit()
text = info.text()
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 a graph window named "test" with two layers disposed on a 2 rows x 1 column grid
g = newGraph("test", 2, 2, 1)
# create an empty 3D plot window with default title
p = newPlot3D()
# create an empty note named "momo"
n = newNote("momo")
# use defaults
n = newNote()
The currently selected Table/Matrix etc. can be accessed with the following commands:

t = currentTable()
m = currentMatrix()
g = currentGraph()
n = currentNote()
The functions will only return a valid object if a window of the wanted type is actually selected. You can check if the object is valid with a simple if clause:
if isinstance(t,qti.Table): print "t is a table"

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").

Once you have established contact with a MDI window, you can modify some of its properties, like the name, the window label, the geometry, etc.. For example, here's how to rename a window, change its label and the way they are displayed in the window title bar, the so called caption policy:

t = table("Table1")
setWindowName(t, "toto")
t.setWindowLabel("tutu")
t.setCaptionPolicy(MDIWindow.Both)
The caption policy can have one of the following values:

  1. Name

    -> the window caption is determined by the window name

  2. Label

    -> the caption is determined by the window label

  3. Both

    -> caption = "name - label"

It is also possible to add comments to a project window. The comments may include line breaks, contrary to the window label:

t = table("Table1")
t.setWindowComment("Experiment name: ...\nDate: ...\nProcedure: ...\n")
print t.windowComment()
Here's how you can access and modify the geometry of a window in the project:

t = table("Table1")
t.setGeometry(10, 10, 800, 600)
print t.x(), t.y(), t.width(), t.height()
For a fast editing process, you can create template files from existing tables, matrices or plots. The templates can be used later on in order to create customized windows very easily:

saveAsTemplate(graph("Graph1"), "my_plot.qpt")
g = openTemplate("my_plot.qpt")
Also, you can easily clone a MDI window:

g1 = clone(graph("Graph1"))
If you want to delete a project window, you can use the close()method. You might want to deactivate the confirmation message, first:

w.confirmClose(False)
w.close()
All QtiPlot subwindows are displayed in a QMdiArea. You can get a pointer to this object via the workspace()method. This can be particularly usefull if you need to customize the behavior of the workspace via your scripts. Here follows a small example script that pops-up a message displaying the name of the active MDI subwindow each time a new window is activated:

def showMessage():
	QtGui.QMessageBox.about(qti.app, "", workspace().activeSubWindow().objectName())

QtCore.QObject.connect(workspace(), QtCore.SIGNAL("subWindowActivated(QMdiSubWindow *)"), showMessage)
It is possible to access the list of all MDI window objects in a QtiPlot project:

for w in qti.app.windows():
	print w.objectName()
...or the list of selected MDI windows in the project explorer:

for w in qti.app.selectedExplorerWindows():
	print w.objectName()

Project Folders

Storing your data tables/matrices and your plots in folders can be very convenient and helpful when you're analyzing loads of data files in the same project. New objects will always be added to the active folder. You can get a pointer to it via:

f = activeFolder()
The functions table, matrix, graph and note will start searching in the active folder and, failing this, will continue with a depth-first recursive search of the project's root folder, given by:

f = rootFolder()
In order to access subfolders and windows, the following functions are provided:

f1 = folder("folder1")
f2 = f.folder("folder2", caseSensitive=True, partialMatch=False)
f3 = f.folders()[2] # f3 is the 3rd subfolder of parent folder f
t = f.table(name, recursive=False)
m = f.matrix(name, recursive=False)
g = f.graph(name, recursive=False)
n = f.note(name, recursive=False)
lst = f.windows()
for w in lst:
	print w.objectName()
If you supply True for the recursive argument, a depth-first recursive search of all subfolders will be performed and the first match returned.

New folders can be created using:


newFolder = addFolder("New Folder", parentFolder = 0)
If the parentFolderis not specified, the new folder will be added as a subfolder of the project's root folder. When you create a new folder via a Python script, it doesn't automatically become the active folder of the project. You have to set this programatically, using:

changeFolder(newFolder, bool force=False)
Folders can be deleted using:

deleteFolder(folder)
It is possible to copy folders within a project:

copyFolder(folder("source"), folder("destination"))
Project windows can be moved between existing folders using:

table("Table1").moveTo(folder("folder1"))
graph("Graph1").moveTo(addFolder("folder2"))
You can save a window or a folder as a project file, and of course, you can also save the whole project:

saveWindow(table("Table1"), "Table1.qti", compress=False)
saveFolder(folder, "new_file.qti", compress=False)
saveProjectAs("new_file_2.qti", compress=False)
saveProject()
print projectName()
If compressis set to True, the project file will be archived to the .gz format, using zlib.

Also, you can load a QtiPlot or an Origin project file into a new folder. The new folder will have the base name of the project file and will be added as a subfolder to the parentFolder or to the current folder if no parent folder is specified.


newFolder = appendProject("projectName", parentFolder = 0)
If you don't want to be asked for confirmation when a table/matrix is renamed during this operation, or when deleting a folder via a Python script, you must change your preferences concerning prompting of warning messages, using the Preferences dialog ("Confirmations" tab).

Folders store their own log information containing the results of the analysis operations performed on the child windows. This information is updated in the result log window each time you change the active folder in the project. You can access and manipulate these log strings via the following functions:


text = folder.logInfo()
folder.appendLogInfo("Hello!")
folder.clearLogInfo()

Finally, it is worth mentioning that it is possible to access the list of all selected folder items in the project explorer:

for folder in qti.app.selectedFolders():
	print folder.name()

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. In many places there is an alternative API which represents a table as a Python sequence is provided. Here rows are addressed by Python indices or slices which start at 0. These places are marked as such.

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)
An alternative way to get/set the value of a cell is using the getter/setter functions bellow. Assigning a Nonevalue will clear the cell:

t.cellData(col, row)
# and
t.setCellData(col, row, value)

Based on the type of the column, QtiPlot handles all the casting under the hood and throws an TypeError if setting the data for a cell isn't possible. The type of a column can be one of the following:

Table.Numeric:

returns/accepts only numerical values.

Table.Text:

returns/accepts only text strings.

Table.Date:

returns/accepts Python datetime.datetime objects and also accepts a QDateTime.


import time
from datetime import datetime
t = newTable("datetime", 2, 1)
t.setColDateFormat(1, "dd/MM/yyyy")
t.setCellData(1, 1, datetime.utcnow()) # from Python datetime object
t.setCellData(1, 2, QDateTime.currentDateTime()) # from QDateTime object
Table.Time:

returns/accepts datetime.time objects and also accepts a QTime.


import time
from datetime import datetime
t = newTable("time", 2, 1)
t.setColTimeFormat(1, "hh:mm:ss")
t.setCellData(1, 1, datetime.now().time()) # from Python time object
t.setCellData(1, 2, QTime.currentTime()) # from QTime object
Table.Month:

accepts any numerical values, including floating point values and internally transforms them to integer values corresponding to the months of the year: 1 (January) to 12 (December, for which also 0 is accepted).

Table.Day:

accepts any numerical values, including floating point values and internally transforms them to integer values corresponding to the days of the week: 1 (monday) to 7 (sunday, for which also 0 is accepted).

Table.TextAndNumeric:

returns/accepts both numerical values and text strings. It is the default type.

You can set the format of a column to text using:

t.setColTextFormat(col)
Or you can adjust the numeric format:

t.setColNumericFormat(col, format, precision)
were colis the number of the column to adjust and precisionstates the number of digits. The formatcan be one of the following:

Table.Default (0)

standard format

Table.Decimal (1)

decimal format with precision digits

Table.Scientific (2)

scientific format

You can reset the Table.TextAndNumeric type for a column if it was modified previously using the following function:

t.setColTextNumericFormat(col, format, precision)
In the same way you can set a column to hold a date. Here the text of a cell is interpreted using a format string:

t.setColDateFormat(col, format)
t.setColDateFormat("col1", "yyyy-MM-dd HH:mm")
were colis the name/number of a column and formatthe format string. In this string, the following placeholder are recognized:

d

the day as number without a leading zero (1 to 31)

dd

the day as number with a leading zero (01 to 31)

ddd

the abbreviated localized day name (e.g. 'Mon' to 'Sun')

dddd

the long localized day name (e.g. 'Monday' to 'Sunday')

M

the month as number without a leading zero (1-12)

MM

the month as number with a leading zero (01-12)

MMM

the abbreviated localized month name (e.g. 'Jan' to 'Dec')

MMMM

the long localized month name (e.g. 'January' to 'December')

yy

the year as two digit number (00-99)

yyyy

the year as four digit number

h

the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)

hh

the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)

H

the hour without a leading zero (0 to 23, even with AM/PM display)

HH

the hour with a leading zero (00 to 23, even with AM/PM display)

m

the minute without a leading zero (0 to 59)

mm

the minute with a leading zero (00 to 59)

s

the second without a leading zero (0 to 59)

ss

the second with a leading zero (00 to 59)

z

the milliseconds without leading zeroes (0 to 999)

zzz

the milliseconds with leading zeroes (000 to 999)

AP or A

interpret as an AM/PM time. AP must be either "AM" or "PM".

ap or a

interpret as an AM/PM time. ap must be either "am" or "pm".

Analog you can say that a text column should hold a time only...

t.setColTimeFormat(col, format)
t.setColTimeFormat(1, "HH:mm:ss")
... a month ...

t.setColMonthFormat(col, format)
t.setColMonthFormat(1, "M")
Here the format is the following:

M

Only the first letter of the month, i.e. "J"

MMM

The short form, like "Jan"

MMMM

The full name, "January"

... or the day of week:

t.setColDayFormat(col, format)
t.setColDayFormat(1, "ddd")
Here the format is the following:

d

Only the first letter of the day, i.e. "M"

ddd

The short form, like "Mon"

dddd

The full name, "Monday"

If you need all the data of a row or column you can use the rowData()and colData()methods. This is much faster then iterating manually over the cells. Alternatively you can use the []operator in combination with Python indices or slices, which start at 0.

valueList = t.colData(col) # col may be a string or a number starting at 1
rowTuple = t.rowData(row) # row number starting at 1
rowTuple = t[idx] # row index starts at 0
rowTupleList = t[slice]
A Table is iterable. The data is returned row wise as tuple.

for c1, c2, c3 in t:
  # do stuff, assuming t has three columns
It is possible to assign row, random or normal random values to a complete column or to a subset of rows in a column:

	t.setRowValues(1, 1, 15)#startRow = 1, endRow = 15
	t.setRandomValues(col, startRow = 1, endRow = -1)
	t.setNormalRandomValues(col, startRow = 1, endRow = -1, standardDeviation = 1.0)
Assigning values to a complete row or column is also possible. While the new row data has to be a tuple which length must match the column number, column data just has to be iteratable. If the iterator stops before the end of the table is reached, a StopIterationexception is raised. In combination with the offsetthis allows to fill a column chunk wise. A positive offset starts filling the column after this row number. A negative offset ignores the first values of the iterator.

t.setColData(col, iterableValueSequence, offset=0)
# just fill the first column with a list of values, staring at row 6
t.setColData(1, [12,23,34,56,67], 5)
# fill the second column with Fibonacci numbers, omitting the first three.
def FibonacciGenerator():
  a, b = 1, 1
  while True:
	a, b = b, a+b
	yield a
t.setColData(2, FibonacciGenerator(), -3)
t.setRowData(row, rowTuple) # row starts at 1
# assuming t has exactly two columns...
t.setRowData(2, (23, 5)) # fill the second row
t[1] = 23, 5 # using a Python index, starting at 0
# adding a new row and set it's values
t.appendRowData(rowTuple)

The number of columns and rows of a table can be accessed or modified using:


t.numRows() # same as len(t)
t.numCols()
t.setNumRows(number)
t.setNumCols(number)
You can add a new column at the end of the table or you can insert new columns before a startColumnusing the functions below:

t.addColumn()
t.insertColumns(startColumn, count)
Adding an empty row at the end of the table is done with the addRow()method. It returns the new row number.

newRowIndex = t.addRow()
It is also possible to swap two columns using:

t.swapColumns(column1, column2)
You can delete a column or a range of rows using the functions below:

t.removeCol(number)
t.deleteRows(startRowNumber, endRowNumber)
It is also possible to use Python's delstatement to remove rows. Note that in this case a Python index or slice (instead of row numbers) is used, which start at 0.

del t[5] # deletes row 6
del t[0:4] # deletes row 1 to 5
Column names can be read and written with:

t.colName(number)
t.colNames()
t.setColName(col, newName, enumerateRight=False)
t.setColNames(newNamesList)
If enumerateRightis set to True, all the table columns starting from index colwill have their names modified to a combination of the newNameand a numerical increasing index. If this parameter is not specified, by default it is set to False. The plural forms get/set all headers at once.

Other column properties like the long name, the unit and the comment can be read/modified using the following methods:


t.setColLongName(1, "Distance")
print t.colLongName(1)
t.setColUnit(1, "nm")
print t.colUnit(1)
t.setColComment(1, "Experiment no. 10")
print t.colComment(1)
You can enable/disable the display of these header label rows via the following functions:

t.showLongName(True)
t.showUnits(False)
t.showComments(True)

You can change the plot role (abscissae, ordinates, error bars, etc...) of a table column col using:


t.setColumnRole(col, role)
print t.columnRole(col)
where rolespecifies the desired column role:

0.

Table.None

1.

Table.X

2.

Table.Y

3.

Table.Z

4.

Table.xErr

5.

Table.yErr

6.

Table.Label

You can normalize a single column or all columns in a table:


t.normalize(col)
t.normalize()
Sort a single or all columns:

t.sortColumn(col, order = 0)
t.sort(type = 0, order = 0, leadingColumnName)

Columns

It is also possible to manipulate individual table columns using their index. Column indices start at 1:


t = newTable("test", 10, 2)
c1 = t.column(1)
c1.setName("A")
c2 = t.column(2)
c2.setName("Date")

Column objects can also be accessed by their name. For example using the test table created with the script above, one gets a referrence to the column objects as follows:


c1 = t.column("A")
c2 = t.column("Date")

Please beware that the column method used above returns a null reference if the table doesn't contain a column with the name you indicated. Once you have a valid reference to a column object, c, you can access all its properties using the following getter functions:


c.name() # column short name
c.longName() # column long name
c.fullName() # returns tableName_shortName
c.unit()
c.comment()
c.command() # the formula set for the column
c.formatInfo() # the format string in case the column type is date/time
c.numericPrecision() # the number of significant digits
c.numericFormat()
c.type()
c.plotRole()
c.isReadOnly()
c.width()
c.size() # returns the number of rows
c.isEmpty() # returns True if all cells in the column are empty
c.lastValidRow() # index of the last non empty cell starting from the bottom
c.hasOnlyTextValues() # returns True if all cells have string values
c.index() # column index in the parent table (leftmost column has index 1)

It is of course possible to modify the above properties using the corresponding setter functions:


c.setName("A")
c.setLongName("test long name")
c.setUnit("cm")
c.setComment("column comment")
c.updateHeaderView() # makes the changes visible in the table header
c.setCommand("sin(0.1*i)")
c.setDateFormat("dd/MM/yyyy") # set format to Table.Date and format string to "dd/MM/yyyy"
c.setTimeFormat("hh:mm:ss")# set format to Table.Time and format string to "hh:mm:ss"
c.setMonthFormat("MMMM") # set Table.Month format; other format strings: "M" and "MMM"
c.setDayFormat("dddd") # set Table.Day format; other format strings: "d" and "ddd"
c.setNumericPrecision(10)
c.setNumericFormat(Table.Decimal, 7) # set decimal format with 7 precision digits
c.setType(Table.Text) # set text format
c.setPlotRole(Table.X)
c.setReadOnly()
c.setReadOnly(False) # reenable column modifications
c.setWidth(90)
c.setHidden() # hides column
c.setHidden(False) # makes column visible

Please note that after setting a new column formula you need to trigger a recalculation of the cell values:


t = newTable("test", 30, 2)
c = t.column(2)
c.setCommand("sin(0.1*i)")
t.recalculate(c.index())

It is straightforward to access cell values using their index, but you must be aware of the fact that for all column functions the row indices start at zero, contrary to table functions where indices start at 1:


val = c.value(0) # returns the value of the 1st cell as a double
string = c.text(0) # returns the text string displayed in the 1st cell

The value of a column cell can be modified using the following setter functions:


c.setValue(0, 1178.14)
c.setText(0, "text string")

QtiPlot stores column cell values either as floating point numerical values (doubles) or as text strings, depending on the column type. If the column type is Table.Date or Table.Time QtiPlot converts internaly the numerical values to a QDateTime object using the Table.dateTime() function and displays them using the format string specified for the column. QtiPlot also provides two methods that allow to perform the reverse conversion from a QDateTime or QTime object to a double floating point numerical value:


val1 = Table.fromDateTime(QDateTime.currentDateTime())
val2 = Table.fromTime(QTime.currentTime())
print val1
print val2

The following script shows how you can fill a table column with date values:


t = newTable("test", 10, 2)
c = t.column(1)
c.setName("Date")
c.setDateFormat("dd/MM/yyyy")

date = QDateTime.currentDateTime()
for i in range(0, c.size()):
	c.setValue(i, Table.fromDateTime(date.addDays(i)))

You can delete the content of a single cell or a range of cells using the functions bellow. Please note that after these operations you need to refresh the table view in order to be able to observe the changes:


c.clearCell(1) # clear 2nd cell
c.clear(0, 9) # clear range from 1st to 10th cell
c.deleteCells(0, 9) # delete/remove range from 1st to 10th cell
c.updateView()

For all column operations that involve a cell range if you don't specify the index of th start row it is by default considered to be zero and if you omit the end row index (or you set it to -1) it is considered to be index of the last/bottom cell:


c.clear(10) # keeps the first 10 cells from top and clears the rest
# it is equivalent to:
c.clear(10, -1)
c.clear() # clears the whole column
c.updateView()

The following functions provide automatic filling of a column with data values:


c.setRowValues(0, 7) # fill cell range with row indices
c.setRandomValues(0, 9) # fill cell range with random values
c.setNormalRandomValues(0, -1, 1.0) # fill column with a Gaussian distribution with standard deviation sigma = 1.0

It is possible to normalize a column to 1 or to sort its values in ascending or descending order:


c.normalize()
c.sort() # sort column in ascending order
c.sort(Qt.DescendingOrder) # sort column in descending order

Finally, it is worth mentioning that you can copy a column (with or without its cell values) from one table to another:


t1 = newTable("test", 10, 3)
t2 = table("Table1")
c1 = t1.column(1)
c1.copy(t2.column(1))
c2 = t1.column(2)
c2.copy(t2.column(2), False) # don't copy data values
c3 = t1.column(3)
c3.copyData(t2.column(3)) # copy only the data values

Statistics on columns

There are a number of predefined statistical functions that can be used for columns having a numerical (not Text) type:


c.rms(0, 9) # returns the root mean square, also known as the quadratic mean
c.sd(0, 10) # returns the standard deviation of a cell range
c.sum(0, 10) # returns the sum of all cells in the range
c.avg(0, 20) # returns the average of a cell range
c.avg() # returns the average of the whole column
c.minValue(0, 9) # returns the minimum value in a cell range
c.minValue() # returns the minimum value in column
c.maxValue(0, 100) # returns the maximum value in a cell range

Data searching

It is possible to search for a text string in a column. The search operation returns the row index of the first occurence of the researched string. If the text string can not be found the function returns -1. Please note that by default the search operation is case insensitive and wildcard characters are allowed.


row = c.find("qti")
print row
row = c.find("Qti", QTextDocument.FindCaseSensitively) # case sensitive search
print row
row = c.find("Tuesday", QTextDocument.FindWholeWords) # find whole words
print row

Data mask

It is possible to mask a data cell or a range of cells in a column using:


c.mask(1, 10)
c.updateView()
print c.isMasked(1) # returns True
print c.hasMaskedCells(11, -1) # returns False

c.swapMask() # set a complementary mask
c.updateView()

Import ASCII files

Import values from file, using sepas separator character, ignoring ignoreLineslines at the beginning of the file and all lines starting with a commentstring.

t.importASCII(file, sep="\t",ignoreLines=0,renameCols=False,stripSpaces=True,simplifySpace=False,
importComments=False,comment="#",readOnly=False,importAs=Table.Overwrite,locale=QLocale(),endLine=0,maxRows=-1)
As you see from the above list of import options, you have the possibility to set the new columns as read-only. This will prevent the imported data from being modified. You have the possibility to remove this protection at any time, by using:

t.setReadOnlyColumn(col, False)

The importAs flag can have the following values:

0.

Table.NewColumns: data values are added as new columns.

1.

Table.NewRows: data values are added as new rows.

2.

Table.Overwrite: all existing values are overwritten (default value).

If the number format in the imported ASCII file does not match the currently used decimal separators convention, you can specify the correct format via the locale variable, like in the example bellow:


t.importASCII("test.txt", ';', 5, True, False, False, True, "", False, Table.Overwrite, QLocale(QLocale.German))

The endLine flag specifies the end line character convention used in the ascii file. Possible values are: 0 for line feed (LF), which is the default value, 1 for carriage return + line feed (CRLF) and 2 for carriage return only (usually on Mac computers).

The last parameter maxRows allows you to specify a maximum number of imported lines. Negative values mean that all data lines must be imported.

Importing Excel sheets

It is possible to import a sheet from an Excel .xls file file to a table, using:


t = importExcel(file, sheet)

Please note that the integer variable sheet starts at 0 and must be lower than the number of sheets in the Excel workbook. If the sheet index is not specified, all non-empty sheets in the Excel workbook are imported into separate tables and a reference to the table containing the data from the last sheet is returned.

Importing ODF spreadsheets

It is possible to import a sheet from an ODF spreadsheet .ods file to a table, using:


t = importOdfSpreadsheet(file, sheet)

Please note that the integer variable sheet starts at 0 and must be lower than the number of sheets in the file. If the sheet index is not specified, all non-empty sheets in the spreadsheet are imported into separate tables and a reference to the table containing the data from the last sheet is returned.

Export Tables

You can export values from a table to an ASCII file, using sep as separator character. The ColumnLabels option allows you to export or ignore the column labels, ColumnComments does the same for the comments displayed in the table header and the SelectionOnly option makes possible to export only the selected cells of the table.


t.exportASCII(file,sep="\t",ColumnLabels=False,ColumnComments=False,SelectionOnly=False)
Other settings that you can modify are the text displayed as a comment in the header of a column...

t.setComment(col, newComment)
... or the expression used to calculate the column values. Please beware that changing the command doesn't automatically update the values of the column; you have to call recalculateexplicitly. Calling it with just the column as argument will recalculate every row. Forcing muParser can speed things up.

t.setCommand(col, newExpression)
t.recalculate(col, startRow=1, endRow=-1, forceMuParser=False, notifyChanges=True)
You can also modify the width of a column (in pixels) or hide/show table columns:

t.setColumnWidth(col, width)
t.hideColumn(col, True)
If one or several table columns are hidden you can make them visible again using:

t.showAllColumns()
You can ensure the visibility of a cell with:

t.scrollToCell(col, row)
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()
While the above is easy to understand, there is a faster and more pythonic way of doing the same:

t = table("table1")
t.setColData(1, [i*i for i in range(len(t))])
t.notifyChanges()
You can check if a column or row of a table is selected by using the following functions:

t.isColSelected(col)
t.isRowSelected(row)

R interface

If RPy2is available, the default initialization filesets up the helper functions qti.Table.toRDataFrameand qti.app.newTableFromRDataFrameto convert back and forth between R data frames and QtiPlot tables. Here is a little example of an R session...

df <- read.table("/some/path/data.csv", header=TRUE)
m <- mean(df)
v <- var(df)
source("/some/path/my_func.r")
new_df <- my_func(df, foo=bar)
... and now the same from within QtiPlot:

df = table("Table1").toRDataFrame()
print R.mean(df), R.var(df)
R.source("/some/path/my_func.r")
new_df = R.my_func(df, foo=bar)
newTableFromRDataFrame(new_df, "my result table")

Working with Matrices

Matrix objects have a dual view mode: either as images or as data tables. Assuming that you have assigned some matrix to the variable m, you can change its display mode via the following function:

m.setViewType(Matrix.TableView)
m.setViewType(Matrix.ImageView)
If a matrix is viewed as an image, you have the choice to display it either as gray scale or using a predefined color map:

m.setGrayScale()
m.setRainbowColorMap()
m.setDefaultColorMap() # default color map defined via the 3D plots tab of the preferences dialog
You can also define custom color maps:

map = LinearColorMap(QtCore.Qt.yellow, QtCore.Qt.blue)
map.setMode(LinearColorMap.FixedColors) # default mode is LinearColorMap.ScaledColors
map.addColorStop(0.2, QtCore.Qt.magenta)
map.addColorStop(0.7, QtCore.Qt.cyan)
m.setColorMap(map)
You have direct access to the color map used for a matrix via the following functions:

map = m.colorMap()
col1 = map.color1()
print col1.green()
col2 = map.color2()
print col2.blue()
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)
An alternative solution to assign values to a Matrix, would be to define a formula and to calculate the values using this formula, like in the following example:

m.setFormula("x*y*sin(x*y)")
m.calculate()
You can also specify a column/row range in the calculate() function, like this:

m.calculate(startRow, endRow, startColumn, endColumn)
Before setting the values in a matrix you might want to define the numeric precision, that is the number of significant digits used for the computations:

m.setNumericPrecision(prec)
You can change the dimensions of a matrix:

m.setDimensions(rows, columns)
m.setNumRows(rows)
m.setNumCols(columns)
Also, like with tables, you can access the number of rows/columns in a matrix:

rows = m.numRows()
columns = m.numCols()
If QtiPlot has been built with support for ALGLIB, you can also change the dimensions of a matrix by resampling it, using bilinear or bicubic interpolation:

m.resample(rows, cols)# bilinear interpolation by default
m.resample(rows, cols, 1) # bicubic interpolation
If ALGLIB is available you can also smooth the matrix data using:

m.smooth()
Matrix objects allow you to define a system of x/y coordinates that will be used when plotting color/contour maps or 3D height maps. You can manipulate these coordinates using the following functions:

xs = m.xStart()
xe = m.xEnd()
ys = m.yStart()
ye = m.yEnd()
m.setCoordinates(xs + 2.5, xe, ys - 1, ye + 1)
You can also define labels, units and comments for the X, Y or Z axis that can be used in plots:

m.setXLabel("Width")
print m.xLabel()
m.setXUnit("cm")
print m.xUnit()
m.setXComment("X axis comment")
print m.xComment()

m.setYLabel("Height")
print m.yLabel()
m.setYUnit("mm")
print m.yUnit()
m.setYComment("Y axis comment")
print m.yComment()

m.setZLabel("Intensity")
print m.zLabel()
m.setZUnit("a.u.")
print m.zUnit()
m.setZComment("Z axis comment")
print m.zComment()
The horizontal and vertical headers of a matrix can display either the x/y coordinates or the column/row indexes:

m.setHeaderViewType(Matrix.ColumnRow)
m.setHeaderViewType(Matrix.XY)
There are several built-in transformations that you can apply to a matrix object. You can transpose or invert a matrix and calculate its determinant, provided, of course, that the conditions on the matrix dimensions, required by these operations, are matched:

m.transpose()
m.invert()
d = m.determinant()
Some other operations, very useful when working with images, like 90 degrees rotations and mirroring, can also be performed. By default rotations are performed clockwise. For a counterclockwise rotation you must set the clockwiseparameter to False.

m.flipVertically()
m.flipHorizontally()
m.rotate90(clockwise = True)
It is possible to perform a Fast Fourier Transform on a matrix:

m.fft() # forward FFT
m.fft(True) # inverse FFT
It is also possible to apply a FFT filter to a matrix:

m.fftFilter(FFTFilter.LowPass, 0.5)
m.fftFilter(FFTFilter.HighPass, 0.5)
m.fftFilter(FFTFilter.BandPass, 0.5, 1.5)
m.fftFilter(FFTFilter.BandBlock, 0.75, 0.9)
Please note that sometimes, after a change in the matrix settings, you need to use the following function in order to update the display:

m.resetView()
Also, it's worth knowing that you can easily import image files to matrices, that can be used afterwards for plotting (see the next section for more details about 2D plots):

m1 = importImage("C:/poze/adi/PIC00074.jpg")
m2 = newMatrix()
m2.importImage("C:/poze/adi/PIC00075.jpg")
The algorithm used to import the image returns a gray value between 0 and 255 from the (r, g, b) triplet corresponding to each pixel. The gray value is calculated using the formula: (r * 11 + g * 16 + b * 5)/32

For custom image analysis operations, you can get a copy of the matrix image view, as a QImage object, via:


image = m.image()
You can export matrices to all raster image formats supported by Qt or to any of the following vectorial image format: EPS, PS, PDF or SVG using:

m.export(fileName)
This is a shortcut function which uses some default parameters in order to generate the output image. If you need more control over the export parameters you must use one of the following functions:

m1.exportRasterImage(fileName, quality = 100, dpi = 0, compression = 0)
m2.exportVector(fileName, color = True)
where the qualityparameter influences the size of the output file. The higher this value (maximum is 100), the higher the quality of the image, but the larger the size of the resulting files. The dpiparameter represents the export resolution in pixels per inch (the default is screen resolution). The compressionparameter can be 0 (no compression) or 1 (LZW) and is only effectif for .tif/.tiff images. It is neglected for all other raster image formats.

You can also import an ASCII data file, using sep as separator characters, ignoring ignore lines at the head of the file and all lines starting with a comment string:


m.importASCII(file, sep="\t", ignore=0, stripSpaces=True, simplifySpace=False, comment="#",
				importAs=Matrix.Overwrite, locale=QLocale(), endLine=0, maxRows=-1)

The importAs flag can have the following values:

0.

Matrix.NewColumns: data values are added as new columns.

1.

Matrix.NewRows: data values are added as new rows.

2.

Matrix.Overwrite: all existing values are overwritten (default value).

The locale parameter can be used to specify the convention for decimal separators used in your ASCII file.

The endLine flag specifies the end line character convention used in the ascii file. Possible values are: 0 for line feed (LF), which is the default value, 1 for carriage return + line feed (CRLF) and 2 for carriage return only (usually on Mac computers).

The last parameter maxRows allows you to specify a maximum number of imported lines. Negative values mean that all data lines must be imported.

Also, you can export values from a matrix to an ASCII file, using sep as separator characters. The SelectionOnly option makes possible to export only the selected cells of the matrix.


m.exportASCII(file, sep="\t", SelectionOnly=False)

Table/Matrix conversion

If you need to get data from a table, in order to use it in a matrix (or vice-versa), you can avoid time consuming copy/paste operations and speed up the whole process by simply converting the table into a matrix:

m = tableToMatrix(table("Table1"))
t = matrixToTable(m)
For the production of contour or surface plots, you can convert a regular XYZ data table ("regular" meaning that cells in the X and Y columns of the table define a regular 2D grid) into a matrix. A tolerance of 15% is used for the X and Y positions when parsing the 2D grid.

m1 = table("Table1").convertToMatrixRegularXYZ("Data")

In the example above "Data" is the name of the Z column. You can also specify the Z column by its number and choose a limited cell range for the conversion like in the example bellow where 0 is the index of the start row and 15 the index of the end row. If no cell range is specified the whole column is used for the conversion.


m2 = table("Table1").convertToMatrixRegularXYZ(2, 0, 15)

You can also convert a random XYZ data table into a matrix ("random" meaning that cells in the X and Y columns of the table do not define a regular 2D grid). In the example bellow "Data" is the name of the Z column, 0 is the number of the start row and 100 is the index of the end row. The resulting matrix will be 400 rows by 500 columns. The last parameter (the radius) is used by the modified Shepard interpolation algorithm to select data points: only the closest 3D nodes whithin the user-specified radius will be used.


m1 = table("Table1").convertToMatrixRandomXYZ("Data", 0, 100, 400, 500, 2.5)
The last five arguments of this method are optional and have "reasonable" default values. You only need to specify the name or the number of the Z column like in the examples bellow:

t = table("Table1")
m1 = t.convertToMatrixRandomXYZ("Data")
m2 = t.convertToMatrixRandomXYZ(2)

Stem Plots

A stem-plot (or stem-and-leaf plot), in statistics, is a device for presenting quantitative data in a graphical format, similar to a histogram, to assist in visualizing the shape of a distribution. A basic stem-plot contains two columns separated by a vertical line. The left column contains the stems and the right column contains the leaves. See Wikipedia for more details.

QtiPlot provides a text representation of a stem-plot. The following function returns a string of characters representing the statistical analysis of the data:


text = stemPlot(Table *t, columnName, power = 1001, startRow = 0, endRow = -1)
where the power variable is used to specify the stem unit as a power of 10. If this parameter is greater than 1000 (the default behavior), than QtiPlot will try to guess the stem unit from the input data and will pop-up a dialog asking you to confirm the automatically detected stem unit.

Once you have created the string representation of the stem-plot, you can display it in any text editor you like: in a note within the project or even in the results log:


resultsLog().append(stemPlot(table("Table1"), "Table1_2", 1, 2, 15))

2D Plots

Graph windows usually display several plot layers. It is possible to get a reference to the active layer:

l = g.activeLayer()
but you can also select a layer by its number:

l = g.layer(num)
The default background color of a graph is white, but it is possible to fill it with a different background color or with a linear gradient brush, using:

g = graph("Graph1")
g.setBackgroundColor(QtGui.QColor(Qt.gray))
g.setGradientBrush(2, 100) # one color gradient
g.setGradientBrush(3, QtGui.QColor(Qt.blue)) # two colors gradient

The plot title


l.setTitle("My beautiful plot")
l.setTitleFont(QtGui.QFont("Arial", 12))
l.setTitleColor(Qt.red)
l.setTitleAlignment(QtCore.Qt.AlignLeft)
The alignment parameter can be any combination of the Qt alignment flags (see the Qt documentationfor more details).

If you want you can remove the plot title using:


l.removeTitle()

You can access the plot title properties using the following getter functions:


print l.titleString()
font = l.titleFont()
color = l.titleColor()
alignment = l.titleAlignment()
Here's how you can add greek symbols in the plot title or in any other text in the plot layer: axis labels, legends:

l.setTitle("normal text <font face=\"Symbol\">greek text</font>")

Using the font specifications, you can also change the color of some parts of the title only:

l=newGraph().activeLayer()
l.setTitle("<font color = red>red</font> <font color = yellow>yellow</font> <font color = blue>blue</font>")

Customizing the axes

Layer axes can be shown/hidden using the following function:

l.enableAxis(int axis, on = True)
where axiscan be any integer value between 0 and 3 or the equivalent reserved word:

0.

Layer.Left

1.

Layer.Right

2.

Layer.Bottom

3.

Layer.Top

The X-Y axes of a plot layer can be exchanged using the following function:

l.exchangeXYAxes()
If an axis is enabled, you can fully customize it via a Python script. For example you can set its title:

l.setAxisTitle(Layer.Bottom, "time (ms)")
l.setAxisTitleFont(Layer.Bottom, QtGui.QFont("Arial", 11))
l.setAxisTitleColor(Layer.Bottom, Qt.blue)
l.setAxisTitleAlignment(Layer.Bottom, Qt.AlignRight)
l.setAxisTitleDistance(Layer.Bottom, 20)
its color and the font used for the tick labels:

l.setAxisColor(Layer.Left, Qt.green)
l.setAxisFont(Layer.Left, QtGui.QFont("Arial", 10))

You can access the axis title properties using the following getter functions:


print l.axisTitleString(Layer.Bottom)
font = l.axisTitleFont(Layer.Top)
color = l.axisTitleColor(Layer.Right)
alignment = l.axisTitleAlignment(Layer.Left)
dist = l.axisTitleDistance(Layer.Left)

The other axis properties can be retrieved using the following methods:


font = l.axisFont(Layer.Top)
color = l.axisColor(Layer.Right)
formula = l.axisFormula(Layer.Bottom)
The tick labels of an axis can be enabled or disabled, you can set their color and their rotation angle:

l.enableAxisLabels(axis, on = True)
l.setAxisLabelsColor(Layer.Bottom, Qt.red)
l.setAxisLabelRotation(Layer.Bottom, 90)
anglecan be any integer value between -90 and 90 degrees.

The properties of the axis labels can be retrieved using:


color = l.axisLabelsColor(Layer.Left)
angle = l.axisLabelsRotation(Layer.Left)

The numerical format of the labels can be set using:


l.setAxisNumericFormat(axis, format, precision = 6, formula)
where formatcan have the following values:

0.

Automatic: the most compact numeric representation is chosen

1.

Decimal: numbers are displayed in floating point form

2.

Scientific: numbers are displayed using the exponential notation

3.

Superscripts: like Scientific, but the exponential part is displayed as a power of 10

precisionis the number of significant digits and formulais a mathematical expression that can be used to link opposite scales. It's argument must be xfor horizontal axes and yfor vertical axes. For example, assuming that the bottom axis displays a range of wavelengths in nanometers and that the top axis represents the equivalent energies in eV, with the help of the code below all the wavelengths will be automatically converted to electron-volts and the result will be displayed in floating point form with two significant digits after the decimal dot sign:

l.setAxisNumericFormat(Layer.Top, 1, 2, "1239.8419/x")
print l.axisFormula(Layer.Top)
The axis ticks can be customized via the following functions:

l.setTicksLength(minLength, majLength)
print l.minorTickLength()
print l.majorTickLength()

l.setMajorTicksType(axis, majTicksType)
l.setMinorTicksType(axis, minTicksType)
l.setAxisTicksLength(axis, majTicksType, minTicksType, minLength, majLength)
where the majTicksTypeand minTicksTypeparameters specify the desired orientation for the major and minor ticks, respectively:

0.

Layer.NoTicks

1.

Layer.Out: outward orientation for ticks, with respect to the plot canvas

2.

Layer.InOut: both inward and outward ticks

3.

Layer.In: inward ticks

minLengthspecifies the length of the minor ticks, in pixels and majLengththe length of the major ticks.

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 type specifies the desired scale type:

0.

Layer.Linear

1.

Layer.Log10

2.

Layer.Ln

3.

Layer.Log2

4.

Layer.Reciprocal

5.

Layer.Probability

6.

Layer.Logit

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.

It is possible to access the scale type of an axis via the following "getter" function:


print l.axisScaleType(Layer.Bottom)

The type of an axis (Numerical, Day, Month, Date/Time, etc...) can be obtained using:


print l.axisType(Layer.Bottom)

It is possible to get information about the scale division of an axis via the following functions:


div = graph("Graph1").activeLayer().axisScaleDiv(Layer.Left)
print div.lowerBound()
print div.upperBound()
print div.range()
Defining a scale range for an axis doesn't automatically disable autoscaling. This means that if a curve is added or removed from the layer, the axes will still automatically adapt to the new data interval. This can be avoided by disabling the autoscaling mode, thus making sure that your scale settings will always be taken into account:

l.enableAutoscaling(False)
l.setSynchronizedScaleDivisions(False)
If you want to rescale the plot layer so that all the data points are visible, you can use the following utility function:

l.setAutoScale()
The same setScalefunction above, with a longer list of arguments, can be used to define an axis break region:

l.setScale(axis, start, end, step=0.0, majorTicks=5, minorTicks=5, type=0, inverted=False,
	left=-DBL_MAX, right=DBL_MAX, breakPosition=50, stepBeforeBreak=0.0, stepAfterBreak=0.0,
	minTicksBeforeBreak=4, minTicksAfterBreak=4, log10AfterBreak=False, breakWidth=4, breakDecoration=True)
where leftspecifies the left limit of the break region, rightthe right limit, breakPositionis the position of the break expressed as a percentage of the axis length and breakWidthis the width of the break region in pixels. The names of the other parameters should be self-explanatory.

You can also invert the scale of an axis using the following direct method:


l.invertScale(Layer.Bottom)
print l.hasInvertedScale(Layer.Bottom)

Finally, you can specify the width of all axes and enable/disable the drawing of their backbone line, using:


l.setAxesLinewidth(2)
l.drawAxesBackbones(True)

The canvas

You can display a rectangular frame around the drawing area of the plot (the canvas) and fill it with a background color, a linear gradient brush or with an image, using:

l.setCanvasFrame(2, QtGui.QColor("red"))
l.setCanvasColor(QtGui.QColor("lightGrey"))
l.setCanvasGradientBrush(3, QtGui.QColor(Qt.blue))
l.setCanvasBackgroundImage("C:/qtiplot/qtiplot/qtiplot_logo.png")
As you have seen above it is possible to fill the canvas with a linear gradient brush. There are sixteen predefined gradient types. The first argument of the "setter" functions is the gradient type and must be a value between 0 and 15. The second argument can be either a color or an integer value. If the second argument is a color the linear gradient interpolates between the canvas background color and the specified color. If you specify an integer value (the lightness) the second color of the linear gradient is a lighter/darker color with respect to the background color. The lightness must be an integer value between 0 (black) and 100 (white).

l.setCanvasGradientBrush(3, QtGui.QColor(Qt.blue))
l.setCanvasGradientBrush(3, 90)
The following access methods are available for the canvas background image:

pic = l.backgroundPixmap() # QPixmap
path = l.canvasBackgroundFileName()
Drawing the canvas frame and disabling the axes backbone lines is the only possible solution for the issue of axes not touching themselves at their ends.

The layer frame

You can display a rectangular frame around the whole layer and fill it with a background color or with a linear gradient brush, using:

l.setFrame(2, QtGui.QColor("blue"))
l.setBackgroundColor(QtGui.QColor("grey"))
l.setGradientBrush(3, QtGui.QColor(Qt.blue))
The default spacing between the layer frame and the other layer elements (axes, title) can be changed via:

l.setMargin(10)

Customizing the grid

You can display the grid associated to a layer axis or the whole grid using:

l.showGrid(axis)
l.showGrid()
l.setGridOnTop(on = True, update = True) # draw grid on top of data
This will display the grid with the default color, width and pen style settings. If you need to change these settings, as well as to enable/disable certain grid lines, you can use the following functions:

grid = l.grid()
grid.setMajPenX(QtGui.QPen(QtCore.Qt.red, 1))
grid.setMinPenX(QtGui.QPen(QtCore.Qt.yellow, 1, QtCore.Qt.DotLine))
grid.setMajPenY(QtGui.QPen(QtCore.Qt.green, 1))
grid.setMinPenY(QtGui.QPen(QtCore.Qt.blue, 1, QtCore.Qt.DashDotLine))
grid.enableXMaj()
grid.enableXMin()
grid.enableYMaj(False)
grid.enableYMin(False)
grid.enableZeroLineX(True)
grid.enableZeroLineY(False)
grid.setXZeroLinePen(QtGui.QPen(QtCore.Qt.black, 2))
grid.setYZeroLinePen(QtGui.QPen(QtCore.Qt.black, 2))
l.replot()
All the grid functions containing an Xrefer to the vertical grid lines, whereas the Yletter indicates the horizontal ones. Also, the Majword refers to the main grid lines and Minto the secondary grid.

The plot legend

Plot legends can be accessed as shown in the script bellow. You should be aware of the fact that not all plot layers have legends. If the legend object was deleted, the instance returned by the legend() function might be null:


layer = graph("Graph1").activeLayer()
legend = layer.legend()
if legend: # the current legend might be NULL
	legend.setOrigin(100, 80)
else:
	print "This layer doesn't have a legend!"
You can add a new legend to a plot using:

legend = l.newLegend()
#or
legend = l.newLegend("enter your text here")
Plot legends are special text objects which are updated each time you add or remove a curve from the layer. They have a special auto-updateflag which is enabled by default. The following function returns Truefor a legend object:

legend.isAutoUpdateEnabled()
You can disable/enable the auto-update behavior of a legend/text object using:

legend.setAutoUpdate(False/True)
You can add common texts like this:

text = l.addText(legend)
text.setOrigin(legend.x(), legend.y()+50)
Please notice that the addTextfunction returns a different reference to the new text object. You can use this new reference later on in order to remove the text:

l.remove(text)
Once you have created a legend/text, it's very easy to customize it. If you want to modify the text you can use:

legend.setText("Enter your text here")
All other properties of the legend: rotation angle, text color, background color, frame style, font and position of the top-left corner can be modified via the following functions:

legend.setAngle(90)
legend.setTextColor(QtGui.QColor("red"))
legend.setBackgroundColor(QtGui.QColor("yellow"))
legend.setFrameStyle(Frame.Shadow)
legend.setFrameColor(QtCore.Qt.red)
legend.setFrameWidth(3)
legend.setFrameLineStyle(QtCore.Qt.DotLine)
legend.setFont(QtGui.QFont("Arial", 14, QtGui.QFont.Bold, True))
# set top-left position using scale coordinates:
legend.setOriginCoord(200.5, 600.32)
# or set top-left position using pixel coordinates:
legend.setOrigin(5, 10)
legend.repaint()
Some of the properties of the legend can be accessed via the following "getter" functions:

angle = legend.angle()
color = legend.textColor()
font = legend.font()
x = legend.xValue()# top position in scale coordinates
y = legend.yValue()# left position in scale coordinates
Other frame styles available for legends are: Legend.Line, which draws a rectangle around the text and Legend.None(no frame at all). There is also a function allowing you to add an automatically built time stamp:

timeStamp = l.addTimeStamp()

Finally, it is possible to iterate over the list of all texts/legends in a plot layer:


layer = graph("Graph1").activeLayer()
for legend in layer.textsList():
	print legend.text()

Antialiasing

Antialiasing can be enabled/disabled for the drawing of the curves and other layer objects, but it is a very resources consuming feature:

l.setAntialiasing(True, bool update = True)

Resizing layers

A layer can be resized using the methods below, where the first argument is the new width, the second is the new height and sizes are defined in pixels:

 l.resize(200, 200);
 l.resize(QSize(w, h))
 
If you also need to reposition the layer, you can use the following functions, where the first two arguments specify the new position of the top left corner of the canvas:

 l.setGeometry(100, 100, 200, 200);
 l.setGeometry(QRect(x, y, w, h));
 
By default, when resizing 2D plot windows, QtiPlot adapts the sizes and aspect of the layers to the new size of the plot window. You can override this behavior and keep the aspect and size of the graph layers unchanged:

g = newGraph("test", 2, 1, 2)
g.arrangeLayers()
g.setScaleLayersOnResize(False)
Also, the default behavior of 2D plot layers with respect to the resizing of the graph window is to adapt the sizes of the fonts used for the various texts, to the new size of the plot window. You can override this behavior and keep the size of the fonts unchanged:

l.setAutoscaleFonts(False)

Resizing the drawing area

The drawing area of a layer (the canvas) can be resized using the methods below, where the first argument is the new width, the second is the new height and sizes are defined in pixels:

 l.setCanvasSize(200, 200);
 l.setCanvasSize(QSize(w, h))
 
If you also need to reposition the canvas, you can use the following functions, where the first two arguments specify the new position of the top left corner of the canvas:

 l.setCanvasGeometry(100, 100, 200, 200);
 l.setCanvasGeometry(QRect(x, y, w, h));
 
Please keep in mind that the fonts of the layer are not rescaled when you resize the layer canvas using the above methods.

Working with 2D curves

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

t = table("Table1")
g = plot(t, column, type)
columncan be either the name of the column (string value) or the column index (integer value) and typespecifies the desired plot type and can be one of the following numbers or the equivalent reserved word:

0

Layer.Line

1

Layer.Scatter

2

Layer.LineSymbols

3

Layer.VerticalBars

4

Layer.Area

5

Layer.Pie

6

Layer.VerticalDropLines

7

Layer.Spline

8

Layer.HorizontalSteps

9

Layer.Histogram

10

Layer.HorizontalBars

13

Layer.Box

15

Layer.VerticalSteps

23

Layer.BSpline

24

Layer.Bezier

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

g1 = plot(table("Table1"), (2,4,7), 2)
g2 = plot(table("Table1"), ("Table1_2","Table1_3"), Layer.LineSymbols)
There are some curve types that specifically request at least two Y columns, the first column in the tuple being used as baseline:

26

Layer.FloatingColumn

27

Layer.FloatingBar

29

Layer.FillArea


l.addCurves(table("Table1"), (2, 3), Layer.FloatingColumn)
l.addCurves(table("Table1"), (2, 3), Layer.FillArea)
Some predefined plot types that can be used to stack the plot curves by adding an offset to their Y values:

21

Layer.StackBar

22

Layer.StackColumn

25

Layer.StackArea

28

Layer.StackLine

30

Layer.StackBarPercent

31

Layer.StackColumnPercent

32

Layer.StackAreaPercent


l.addCurves(table("Table1"), (2, 3), Layer.StackColumn)
The stack offset can be customized using one of the following modes:

0

Layer.NoOffset

1

Layer.CumulativeOffset

2

Layer.ConstantOffset

3

Layer.AutoOffset

4

Layer.IndividualOffset


l.addCurves(table("Table1"), (2, 3), Layer.StackLine)
l.stackCurves(Layer.AutoOffset, 0.1)
In the example above the relative gap between the plot curves was set to 10% (0.1). The offset can be set to a constant value if the stack mode is set to Layer.ConstantOffset:

l.addCurves(table("Table1"), (2, 3), Layer.Line)
l.stackCurves(Layer.ConstantOffset, 1000)
or you can specify a different offset for each plot curve:

l.addCurves(table("Book1"), ("B", "C"), Layer.Area)
l.stackCurves(Layer.IndividualOffset)
c = l.dataCurve(1)
c.setOffset(2, 500)
print c.xOffset(), c.yOffset()
In the case of the following plot types: StackAreaPercent, StackBarPercentand StackColumnPercentthe stack mode is set to CumulativeOffsetand the data values are percent normalized. A special hasPercentNormalizedStackflag is set for these plot types:

print l.hasPercentNormalizedStack()
which of course can be disabled:

l.setPercentNormalizedStack(False)
l.stackCurves(Layer.CumulativeOffset)
You can add or remove curves to or from a plot layer:

l.insertCurve(table, Ycolumn, type=Layer.Scatter, int startRow = 0, int endRow = -1)# returns a reference to the inserted curve
l.insertCurve(table, Xcolumn, Ycolumn, type=Layer.Scatter, int startRow = 0, int endRow = -1)# returns a reference to the inserted curve
l.addCurve(table, column, type=Layer.Line, lineWidth = 1, symbolSize = 3, startRow = 0, endRow = -1)# returns True on success
l.addCurves(table, (2,4), type=Layer.Line, lineWidth = 1, symbolSize = 3, startRow = 0, endRow = -1)# returns True on success
l.removeCurve(curveName)
l.removeCurve(curveIndex)
l.removeCurve(curveReference)
l.deleteFitCurves()
It is possible to copy all the curves from a source plot layer lSrcto a destination layer lDest:

lSrc = graph("Graph1").activeLayer()
lDest = newGraph().activeLayer()
lDest.copyCurves(lSrc)
Of course, you can also clone an entire plot layer:

lDest.copy(lSrc)
It is possible to change the order of the curves inserted in a layer using the following functions:

l.changeCurveIndex(int oldIndex, int newIndex)
l.reverseCurveOrder()
You can also change the Z order of the curves:

l.switchCurveZ(int oldIndex, int newIndex);
l.reverseCurveZOrder()
If the table column used to create a plot curve has empty cells, you can choose whether the curve line is drawn connected across the missing data or not. This behavior can be specified using:

l.showMissingDataGap(on = True, replot = True)
Sometimes, when performing data analysis, one might need the curve title. It is possible to obtain it using the method below:

title = l.curveTitle(curveIndex)
It is possible to get a reference to a curve on the layer l using it's index or it's title, like shown below:

c = l.curve(curveIndex)
c = l.curve(curveTitle)
dc = l.dataCurve(curveIndex)

Please, keep in mind the fact that the above methods might return an invalid reference if the curve with the specified index/title is not a PlotCurve or a DataCurve object, respectively. For example, an analytical function curve is a PlotCurve but not a DataCurve and spectrograms are a completely different type of plot items which are neither PlotCurves nor DataCurves.

Once you have a reference to a PlotCurve c it is possible to get its type and title using the methods bellow:

c = graph("Graph1").activeLayer().curve(0)
print c.type()
print c.name()

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


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

where number is the index of the curve (starting at zero), x-axis is either Layer.Bottom or Layer.Top and y-axis is either Layer.Left or Layer.Right.

The following functions give information about the axes to which a curve is attached:


print c.xAxis()
print c.yAxis()
In case you need the number of curves on a layer, you can get it with

l.numCurves()
It is possible to change the number of symbols to be displayed for a curve using the function below. This option can be very usefull for very large data sets:

c.setSkipSymbolsCount(3)
print c.skipSymbolsCount()
Once you have added a curve to a plot layer you can fully customize it's appearance:

l = newGraph().activeLayer()
l.setAntialiasing()
c = l.insertCurve(table("Table1"), "Table1_2", Layer.LineSymbols)
c.setPen(QtGui.QPen(Qt.red, 3))
c.setBrush(QtGui.QBrush(Qt.darkYellow))
c.setFillAreaColor(Qt.green)
c.setGradientBrush(3, QtGui.QColor(Qt.blue))
c.setSymbol(PlotSymbol(PlotSymbol.Hexagon, QtGui.QBrush(Qt.yellow), QtGui.QPen(Qt.blue, 1.5), QtCore.QSize(15, 15)))
When you define a filling brush for the area beneath a plot curve the baseline of the filling area is by default the line y = 0. Nevertheless you can specify a different plot curve to act as a custom baseline:

l = newGraph().activeLayer()
c1 = l.addFunction("sin(x)", 0, 2*pi, 100)
c2 = l.addFunction("cos(x)", 0, 2*pi, 100)
c2.setBrush(QtGui.QBrush(Qt.darkYellow))
c2.setBaselineCurveName(c1.name())
print c2.baselineCurveName()
In the case of DataCurves you can also specify a data column as the custom baseline:

c.setBaselineColumn("Table1_2") # the data source of curve c is table "Table1"
print c.baselineColumnName()
An alternative way of customizing a curve in terms of color, line width and line style is by using the functions below, where the first argument is the curve index:

l.setCurveLineColor(0, QtGui.QColor(Qt.red))
# or:
l.setCurveLineColor(0, 1) # set color by its index in the default QtiPlot color list: 0 = black, 1 = red, 2 = green, etc...
l.setCurveLineStyle(0, Qt.DashLine)
l.setCurveLineWidth(0, 0.5) # set the linewidth to 0.5
Here's a short script showing these functions at work:

t = newTable("test", 30, 4)
for i in range(1, t.numRows()+1):
	t.setCell(1, i, i)
	t.setCell(2, i, i)
	t.setCell(3, i, i+2)
	t.setCell(4, i, i+4)

l = qti.app.plot(t, (2,3,4), Layer.Line).activeLayer() # plot columns 2, 3 and 4
for i in range(0, l.numCurves()):
	l.setCurveLineColor(i, 1 + i)
	l.setCurveLineWidth(i, 0.5 + i)
	l.setCurveLineStyle(1, 1 + i)

It is possible to define a global color policy for the plot layer using the following convenience functions:

l.setGrayScale()
l.setGradientColorScale(Qt.yellow, Qt.cyan)
l.setIndexedColors() # uses the colors in the default QtiPlot color list: 0 = black, 1 = red, 2 = green, etc...
Other useful functions allowing to edit the style of all the curves in a plot layer with a single call are:

l.incrementLineStyle()
l.incrementFillPattern()
If you need to change the range of data points displayed in a DataCurve you can use the following methods:

c.setRowRange(int startRow, int endRow)
c.setFullRange()
Also, you can hide/show a plot curve via:

c.setVisible(bool on)
In case you need to get information about the data stored in the curve, you have at your disposal the functions below:

points = c.dataSize()
for i in range (0, points):
	print i, "x = ", c.x(i), "y = ", c.y(i)

print c.minXValue()
print c.maxXValue()
print c.minYValue()
print c.maxYValue()

Curve symbols

Here's how you can customize the plot symbol used for a 2D plot curve c:

s = c.symbol()
s.setSize(QtCore.QSize(7, 7))# or s.setSize(7)
s.setBrush(QtGui.QBrush(Qt.darkYellow))
s.setPen(QtGui.QPen(Qt.blue, 3))
s.setStyle(PlotSymbol.Diamond)
l.replot() # redraw the plot layer object
The symbol styles available in QtiPlot are:

-1

PlotSymbol.NoSymbol

0

PlotSymbol.Ellipse

1

PlotSymbol.Rect

2

PlotSymbol.Diamond

3

PlotSymbol.Triangle

4

PlotSymbol.DTriangle

5

PlotSymbol.UTriangle

6

PlotSymbol.LTriangle

7

PlotSymbol.RTriangle

8

PlotSymbol.Cross

9

PlotSymbol.XCross

10

PlotSymbol.HLine

11

PlotSymbol.VLine

12

PlotSymbol.Star1

13

PlotSymbol.Star2

14

PlotSymbol.Hexagon

15

PlotSymbol.Pentagon

16

PlotSymbol.Star3

It is also possible to define a custom image as the plot symbol for a curve:

g = newGraph().activeLayer()
c = g.addFunction("cos(x)", 0, 10, 20)
c.setSymbol(ImageSymbol("qtiplot/manual/html/icons/help.png"))
Here's a short script showing how to draw a custom plot symbol and assign it to a curve:

pix = QtGui.QPixmap(QtCore.QSize(11, 11))
pix.fill(Qt.transparent)
p = QtGui.QPainter(pix)
r = QtCore.QRect(0, 0, 10, 10)
p.drawEllipse(r)
p.setPen(QtGui.QPen(Qt.red))
p.drawLine(5, 0, 5, 10)
p.drawLine(0, 5, 10, 5)
p.end()

g = newGraph().activeLayer()
c = g.addFunction("sin(x)", 0, 10, 20)
c.setSymbol(ImageSymbol(pix))
You can also use Unicode characters as plot symbols for a curve:

g = newGraph().activeLayer()
c = g.addFunction("sin(x)", 0, 10, 20)
symbol = UnicodeSymbol(0x273D)
symbol.setFontSize(22)
symbol.setPen(Qt.red)
c.setSymbol(symbol)
It is also possible to define variable sizes for the symbols of a plot curve by indexing the cell values from a table column. This special column can be specified via the setSymbolSizeColumnmethod. Additionally you may set a scaling factor for the symbol size like in the small script bellow:

t = table("Table1")
g = qti.app.plot(t, "Table1_2", Layer.Scatter).activeLayer()
c = g.curve(0)
c.setSymbolSizeColumn(t, "Table1_3")
c.setSymbolScalingFactor(15)
print c.symbolSizeColumnName(), c.symbolScalingFactor()
An equivalent way of obtaining the same result as with the script above is to use the specialized function plotBubbles. You need to specify two Y columns as argument of this function. The first Y column in the tuple is used for the positions of the plot symbols and the next one determines their sizes, see the example bellow:

c = newGraph().activeLayer().plotBubbles(table("Table1"), ["2", "3"])
print c.symbolSizeColumnName(), c.symbolScalingFactor()

Curve labels

It is possible to display labels for each data point in a DataCurve. The labels can be set using the method bellow:

c.setLabelsForm(DataCurve.YValues)
and may have one of the following predefined forms:

0

DataCurve.XValues

1

DataCurve.YValues

2

DataCurve.RowIndices

3

DataCurve.XYValues

You may also specify the labels using the texts in a table column:

c.setLabelsColumnName("Table1_2")
If the labels have numerical values, you can change their display format and precision:

c.setLabelsNumericFormat(2, 3)# display labels with scientific format and three significant digits
c.setLabelsNumericPrecision(2)
The available formats are:

0.

Automatic: the most compact numeric representation is chosen

1.

Decimal: numbers are displayed in floating point form (10.000)

2.

Scientific: numbers are displayed using the exponential notation (1e4)

The position of the labels can be set using the method bellow:

c.setLabelsAlignment(DataCurve.Right)
The following predefined positions can be used:

0

DataCurve.Center

1

DataCurve.Left

2

DataCurve.Right

3

DataCurve.Above

4

DataCurve.Bellow

If the data curve is a column/bar/histogram curve the following predefined positions should be used instead:

0

DataCurve.Center

1

DataCurve.InsideEnd

2

DataCurve.InsideBase

3

DataCurve.OutsideEnd

Other properties of the labels can be customized using the functions bellow:

c.setLabelsOffset(50, 50)
c.setLabelsColor(Qt.red)
c.setLabelsFont(QtGui.QFont("Arial", 14))
c.setLabelsRotation(45)
You can disable the labels of a data curve using:

c.clearLabels()
l.replot() # redraw the plot layer object

Curve drop shadow

It is possible to enable/disable the display of drop shadows for all curves in a plot layer at once:

g = graph("Graph1").activeLayer()
# set shadow color to light gray, offset to 5 pixels and blur radius to 8
g.setDropShadowProperties(Qt.lightGray, 5, 8.0)
g.enableCurveDropShadows(True)
It is equally possible to enable/disable the drop shadow effect for each curve individually:

g = graph("Graph1").activeLayer()
c = g.curve(0)
if (c.hasDropShadow()):
	c.enableDropShadow(False)
g.replot()

Selecting a data range

You can activate the "Select Data Range" tool for a plot layer and select the active curve using the following method:

g = graph("Graph1").activeLayer()
g.enableRangeSelectors()
g.setSelectedCurve(g.curve(0))
g.setActivePoint(20)
g.switchActiveMarker()
g.setActivePoint(90)
g.replot()
If a plot curve is selected you can get the coordinates of the selected data points using the method bellow:

c = g.selectedDataCurve()
print c.x(g.selectionActivePoint())
print c.y(g.selectionActivePoint())
print c.tableRow(g.selectionActivePoint()) + 1
print c.tableRow(g.selectionInactivePoint()) + 1
All 2D plot tools can be disabled using:

g.disableTools()

2D Analytical Functions

You can also add analytical function curves to a plot layer:

f = l.addFunction("x*sin(x)", 0, 3*pi, points = 100)
f.setTitle("x*sin(x)")
f.setPen(Qt.green)
f.setBrush(QtGui.QColor(0, 255, 0, 100))

l.addParametricFunction("cos(m)", "sin(m)", 0, 2*pi, points = 100, variableName = "m")
l.addPolarFunction("t", "t", 0, 2*pi, points = 100, variableName = "t")
It is possible to get a reference to an analytical function curve on the layer l using it's index, like shown below:

f = l.functionCurve(curveIndex)
When dealing with analytical function curves, you can customize them using the following methods:

f.setRange(0, 2*pi)
f.setVariable("t")
f.setComment("My function")
f.setFormulas("sin(t)", "cos(t)")
f.setFunctionType(FunctionCurve.Polar) # or c.setFunctionType(FunctionCurve.Parametric)
f.loadData(1000, xLog10Scale = False)

f.setFunctionType(FunctionCurve.Normal)
f.setFormula("cos(x)")
f.loadData()
If you need to access the values and names of a function's parameters, you have at your disposal the following methods:

i = f.parametersCount() # the number of parameters in your function formula
name = f.parameterName(index) # the name of the parameter of rang index as a QString
p1 = f.parameterValue(index) # the value of the parameter of rang index as a double
p2 = f.parameterValue(name) # the value of a parameter using its name string
The abscissae range for which the function is calculated/displayed, can be obtained/modified via the methods below:

x1 = f.startRange()
x2 = f.endRange()
f.setRange(0.5, 15.2)

Error Bars

Having a plot layer l, you can add error bars to a data curve c, named curveName, using the following methods:

err1 = l.addErrorBars(c, Table *t, QString errColName, int type = 1, double width = 1, int capLength = 8, color = Qt.black, throughSymbol = True, minusSide = True, plusSide = True)
err2 = l.addErrorBars(curveName, Table *t, QString errColName, int type = 1, double width = 1, int capLength = 8, color = Qt.black, throughSymbol = True, minusSide = True, plusSide = True)
Each data curve, c, can have attached a list of error bars:

errors = c.errorBarsList()
The properties of an error bar curve can be accesses, via the following methods:

err = c.errorBarsList()[0]
for i in range(0, err.dataSize()):
	print err.errorValue(i)

err.capLength()
err.width()
err.color()
err.direction()
err.xErrors()
err.throughSymbol()
err.plusSide()
err.minusSide()
c = err.masterCurve() # reference to the master curve to which the error bars curve is attached.
err.detachFromMasterCurve() # equivalent to c.removeErrorBars(err)
... and can be modified, via the following methods:

err.setCapLength(12)
err.setWidth(3)
err.setColor(Qt.red)
err.setDirection(ErrorBarsCurve.Vertical)
err.setXErrors(True) # equivalent to err.setDirection(ErrorBarsCurve.Horizontal)
err.drawThroughSymbol(True)
err.drawPlusSide(True)
err.drawMinusSide(False)
err.setMasterCurve(c)
You can remove all error bars attached to a curve using:

c.clearErrorBars()

Image and Contour Line Plots (Spectrograms)

As you have seen in the previous section, it is possible create 2D plots from matrices. Here's how you can do it in practice:

m = importImage("C:/poze/adi/PIC00074.jpg")
g1 = plot(m, Layer.ColorMap)
g2 = plot(m, Layer.Contour)
g3 = plot(m, Layer.GrayScale)
The plot functions above return a reference to the multilayer plot window. If you need a reference to the spectrogram object itself, you can get it as shown in the example below:

m = newMatrix("TestMatrix", 1000, 800)
m.setFormula("x*y")
m.calculate()
g = plot(m, Layer.ColorMap)
s = g.activeLayer().spectrogram(m)
s.setColorBarWidth(20)
It is possible to fine tune the plots created from a matrix:

m = newMatrix("TestMatrix", 1000, 800)
m.setFormula("x*y")
m.calculate()

s = newGraph().activeLayer().plotSpectrogram(m, Layer.ColorMap)
s.setContourLevels((20.0, 30.0, 60.0, 80.0))
s.setDefaultContourPen(QtGui.QPen(Qt.yellow)) # set global pen for the contour lines
s.setLabelsWhiteOut(True)
s.setLabelsColor(Qt.red)
s.setLabelsFont(QtGui.QFont("Arial", 14))
s.setLabelsRotation(45)
s.showColorScale(Layer.Top)
s.setColorBarWidth(20)
As you have seen earlier, you can set a global pen for the contour lines, using:

s.setDefaultContourPen(QtGui.QPen(Qt.yellow))
You can also assign a specific pen for each contour line, using the function below:

s.setContourLinePen(index, QPen)
or you can automatically set pen colors defined by the color map of the spectrogram:

s.setColorMapPen(bool on = True)
You can also use any of the following functions:

s.setMatrix(Matrix *, bool useFormula = False)
s.setUseMatrixFormula(bool useFormula = True)# calculate data to be drawn using matrix formula (if any)
s.setLevelsNumber(int)
s.showColorScale(int axis, bool on = True)
s.setGrayScale()
s.setDefaultColorMap()
s.setCustomColorMap(LinearColorMap map)
s.showContourLineLabels(bool show = True) # enable/disable contour line labels
s.setLabelsOffset(int x, int y) # offset values for all labels in % of the text size
s.updateData()

Histograms

As you have seen in the previous section, it is possible to create 2D histograms from matrices or tables. The script bellow shows a straightforward way of plotting a histogram from a table column:

h = newGraph().activeLayer().addHistogram(table("Table1"), "Table1_2")
h.setBinCount(5, 1, 30)# the number of bins is set to 5, data range is set to [1, 30]
or from a matrix:

g = plotHistogram(matrix("Matrix1")).activeLayer()
A more complex plot type that displays a histogram together with the corresponding cumulative probabilities can be created:

g1 = plotHistogramProbabilities(table("Table1"), "Table1_2").activeLayer()
g2 = plotHistogramProbabilities(matrix("Matrix1")).activeLayer()
It is also possible to get a reference to a previously created histogram and to modify it according to your needs:

g = graph("Graph1").activeLayer()
h = g.histogram(0)# g is a plot containing one histogram
h.setBinCount(8, 1, 30)
g.replot()
Here's a small script showing how to customize a histogram and how to get access to the statistical information in the histogram (bin positions, counts, mean, standard deviation, etc...):

m = newMatrix("TestHistogram", 1000, 800)
m.setFormula("x*y")
m.calculate()

g = newGraph().activeLayer()
h = g.addHistogram(m)
h.setBinSize(10, 1, 90) # the bin size is set to 10, data range is set to [1, 90]

# print histogram values:
for i in range (0, h.dataSize()):
	print 'Bin {0}: start = {1}, counts = {2}'.format(i + 1, h.x(i), h.y(i))

# print statistic information:
print "Standard deviation = ", h.standardDeviation()
print "Mean = ", h.mean()
print "Maximum = ", h.maximum()
print "Minimum = ", h.minimum()
print "Number of bins = ", h.binCount()
print "Bin size = ", h.binSize()
You can also enable autobinning (a default number of ten bins will be used):

h.setAutoBinning()

Box and whiskers plots

The following script shows how to create and customize a box and whiskers plot:

g = newGraph().activeLayer()
g.plotBox(table("Table1"), ["2", "3", "4"])
for i in range (0, g.numCurves()):
		box = g.boxCurve(i)
		if (box):
			box.setBrush(QtGui.QBrush(Qt.red, Qt.BDiagPattern))
			s = PlotSymbol()
			s.setPen(QtGui.QPen(Qt.blue, 2))
			s.setSize(QtCore.QSize(10, 10))
			box.setSymbol(s)
			box.setMeanStyle(PlotSymbol.Cross)
			box.setBoxStyle(BoxCurve.WindBox)
			box.setBoxWidth(80)
			box.setWhiskersRange(BoxCurve.SD) # standard deviation
The following functions give access to the statistics information for the data series displayed with a box and whiskers plot:

s = box.statistics() # returns information as a string
m = box.median()
q = box.quantile(f) # f must be a fraction between 0 and 1
For an exhaustive review of the methods giving access to the properties of a box plot, please consult the QtiPlot/Python API.

Distribution Curves

For histograms and box and whiskers plots it is also possible to overlay a distribution curve on the binned data. These curves are not "fitted" to your data. Instead, QtiPlot determines the data mean, then overlays the curve so that means coincide. If it is a two parameter curve, QtiPlot takes into account the standard deviation of your data. The following distribution types can be used:

0

DataCurve.NoCurve

1

DataCurve.Normal

2

DataCurve.Lognormal

3

DataCurve.Poisson

4

DataCurve.Exponential

5

DataCurve.Laplace

6

DataCurve.Lorentz

7

DataCurve.Weibull


h = newGraph().activeLayer().addHistogram(table("Table1"), "Table1_2")
h.setDistributionCurve(DataCurve.Normal, 50)# the distribution curve is scaled to 50% of the maximum bin value
h.loadData()
The following functions give access to the distribution curve and its properties:

dc = h.distributionCurve()
dc.setPen(Qt.red)
print h.distributionScaleFactor()
When working with box and whiskers plots you can enable the distribution curve in the same way:

g = newGraph().activeLayer()
g.plotBox(table("Table1"), "2")
box = g.boxCurve(0)
box.setDataDisplayMode(BoxCurve.BoxData)
box.setSnapDataToBin()
g.replot()
box.setDistributionCurve(DataCurve.Poisson)
box.updateHistogram()
box.distributionCurve().setPen(Qt.blue)

Pie Plots

The following script shows how to create and customize a 3D pie plot:

g = newGraph().activeLayer()
pie = g.plotPie(table("Table1"), "2")
pie.setRadius(70)
pie.setViewAngle(40)
pie.setThickness(20)
pie.setStartAzimuth(45)
pie.setLabelsEdgeDistance(50)
pie.setCounterClockwise(True)
pie.setBrushStyle(Qt.Dense3Pattern)
pie.setIncrementPattern(True)
pie.setFirstColor(3)
pie.setPen(QtGui.QPen(Qt.red, 2))
pie.setLabelValuesFormat(True)
Here's how you can create a 2D black and white pie chart:

pie2D = newGraph().activeLayer().plotPie(table("Table1"), "2")
pie2D.setViewAngle(90.0);
pie2D.setFirstColor(-1);
pie2D.setIncrementPattern();
For an exhaustive review of the methods giving access to the properties of a pie plot, please consult the QtiPlot/Python API.

Vector Plots

You can create a vector plot by giving four columns in a Python tuple as an argument and the plot type as Layer.VectXYXY (11) or Layer.VectXYAM (14), depending on how you want to define the end point of your vectors: using (X, Y) coordinates or (Angle, Magnitude) coordinates.


g = qti.app.plot(table("Table1"), (2,3,4,5), Layer.VectXYXY)

In the case of XYAM vector plots you can set a constant angle and/or magnitude, but you still need to specify at least two column names in order to define the origin of the vectors. The following script shows how to create and customize XYAM vector curves:


g = newGraph().activeLayer()
t = table("Table1")

v = g.plotVectors(t, ["Table1_1", "Table1_2"], Layer.VectXYAM)
v.setConstantAngle(135)
v.setConstantMagnitude(15)
v.setPosition(VectorCurve.Head)

v = g.plotVectors(t, ["Table1_1", "Table1_2", "Table1_3"], Layer.VectXYAM)
v.setConstantMagnitude(10)
v.setMagnitudeInPixels()
v.setVectorPen(Qt.red)

v = g.plotVectors(t, ["Table1_1", "Table1_2", "", "Table1_3"], Layer.VectXYAM)
v.setConstantAngle(90)
v.setVectorPen(Qt.blue)

v = g.plotVectors(t, ["Table1_1", "Table1_2", "Table1_3", "Table1_4"], Layer.VectXYAM)
v.setVectorPen(Qt.green)
v.fillArrowHead(False)
v.setHeadAngle(15)
v.setHeadLength(20)
v.setMagnitudeMultiplier(10)
v.setPosition(VectorCurve.Middle)

By default the magnitudes are interpreted in real world coordinates and are used to compute the x, y values of the end point of the vector. The magnitudes displayed in the graph will change when the X or Y axes scales are changed, but they will remain constant in real world coordinates. By using the method setMagnitudeInPixels with the default True argument, the magnitudes will be calculated in pixels and will remain constant when the X or Y axes scales are changed. The same effect can be obtained by using the setRealWorldMagnitude(False) method.

For an exhaustive review of the methods giving access to the properties of a vector curve, please consult the QtiPlot/Python API.

Adding arrows/lines to a plot layer


arrow = ArrowMarker()
arrow.setStart(210.5, 212.5)
arrow.setEnd(400, 400.51)

#customize line
arrow.setStyle(QtCore.Qt.DashLine)
arrow.setColor(Qt.red)
arrow.setWidth(1)

#customize start arrow head
arrow.setStartArrowShape(Layer.VerticalLine)
arrow.setStartHeadLength(15)
arrow.setStartHeadAngle(25)

#customize end arrow head
arrow.setEndArrowShape(Layer.FilledAngle)
arrow.setEndHeadLength(20)
arrow.setEndHeadAngle(15)

l = newGraph().activeLayer()
arrow1 = l.addArrow(arrow)

arrow.setStart(120.5, 320.5)
arrow.setColor(Qt.blue)
arrow2 = l.addArrow(arrow)

l.remove(arrow1)

As you might notice from the sample code above, the addArrow function returns a reference to a new arrow object that can be used later on to modify this new arrow or to delete it with the remove function.

The shape of an arrow head can take one of the following values:

0.

Layer.NoArrow

1.

Layer.FilledTriangle

2.

Layer.Angle

3.

Layer.FilledAngle

4.

Layer.EmptyTriangle

5.

Layer.Diamond

6.

Layer.VerticalLine

7.

Layer.HalfLineDown

8.

Layer.HalfLineUp

9.

Layer.XCross

10.

Layer.Rectangle

11.

Layer.Ellipse

It is possible to modify the properties of all the lines/arrows in a plot layer, see the short example below:


l = graph("Graph1").activeLayer()
for arrow in l.arrowsList():
	arrow.setColor(Qt.green)
l.replot()

The number of lines/arrows in a plot layer can be retrieved using the function numArrows:


l = graph("Graph1").activeLayer()
print l.numArrows()
Starting with version 0.9.9.3 the functions bellow are deprecated. These methods are still provided in order to keep old source code working but they are no longer maintained. We strongly advise against using them in new code.

drawStartArrow(bool)
drawEndArrow(bool)
fillArrowHead(bool)
setHeadLength(int)
setHeadAngle(int)

Adding images to a layer


l = newGraph().activeLayer()
image = l.addImage("C:/poze/adi/PIC00074.jpg")
image.setCoordinates(200, 800, 800, 200)
image.setFrameStyle(Frame.Shadow)
image.setFrameColor(QtCore.Qt.green)
image.setFrameWidth(3)
l.replot()
The setCoordinatesfunction above can be used to set the geometry of the image using scale coordinates. If you need to specify the image geometry in pixel coordinates, independently of the plot axes values, you may use the following functions:

image.setOrigin(x, y)
image.setSize(width, height)
image.setRect(x, y, width, height)
l.replot()
You can remove an image using its reference:

l.remove(image)

Rectangles


l = newGraph().activeLayer()

r = Rectangle(l)
r.setSize(100, 100)
r.setOrigin(100, 200)
r.setBackgroundColor(QtCore.Qt.yellow)
r.setFrameColor(QtCore.Qt.red)
r.setFrameWidth(3)
r.setFrameLineStyle(QtCore.Qt.DotLine)
r.setBrush(QtGui.QBrush(QtCore.Qt.green, QtCore.Qt.FDiagPattern))

r1 = l.add(r)
You can remove a rectangle using its reference:

r2 = l.add(r)
r2.setOrigin(200, 200)
l.remove(r1)

Circles/Ellipses


l = newGraph().activeLayer()

e = Ellipse(l)
e.setSize(100, 100)
e.setOrigin(100, 200)
e.setBackgroundColor(QtCore.Qt.yellow)
e.setFrameColor(QtCore.Qt.red)
e.setFrameWidth(0.8)
e.setFrameLineStyle(QtCore.Qt.DotLine)
e.setBrush(QtGui.QBrush(QtCore.Qt.green, QtCore.Qt.FDiagPattern))

l.add(e)

Exporting graphs

Layers and whole graph windows can be printed and exported from within Python. The fastest way to export a graph window or single layers is the following:

l.export(fileName)
This function uses some default parameters for the properties of the image. If you need more control over the exported images you can use one of the following specialized functions:

l.exportVector(fileName, size = QtCore.QSizeF(), unit = Frame.Pixel, fontsFactor = 1.0, color = True)
l.exportImage(fileName, quality = 100, transparent = False, dpi = 0, size = QtCore.QSizeF(), unit = Frame.Pixel, fontsFactor = 1.0, compression = 0)
l.exportTex(fileName, color = True, escapeStrings = True, fontSizes = True, size = QtCore.QSizeF(), unit = Frame.Pixel, fontsFactor = 1.0)

When exporting graph windows there is an extra boolean parameter that can be used in order to clip the space around plot layers. This last parameter has no effect if used in conjunction with a custom export size. An example of how you should call these functions can be found bellow:


g = graph("Graph1")
g.exportVector("test.pdf", QtCore.QSizeF(), Frame.Pixel, 1.0, True, True)
g.exportImage("test.png", 100, True, 0, QtCore.QSizeF(), Frame.Pixel, 1.0, 0, True)
g.exportTex("test.tex", True, True, True, QtCore.QSizeF(), Frame.Pixel, 1.0, True)

The function exportVector can export the plot/layer to the following vector formats: .eps, .emf, .ps, .pdf, .svg and .wmf (this last format is only supported on Windows platforms). The use of the color parameter only makes sense when exporting to .eps, .pdf and .ps formats. For all other formats it is ignored.

The function exportImage can be used if you need to export to one of the Qt supported raster image formats (.bmp, .png, .jpg, etc...). The transparent option can only be used in conjunction with the file formats supporting transprency: .png and .tif (.tiff). The quality parameter influences the size of the output file. The higher this value (maximum is 100), the higher the quality of the image, but the larger the size of the resulting files. The dpi parameter represents the export resolution in pixels per inch (the default is screen resolution), size is the printed size of the image (the default is the size on screen) and unit is the length unit used to express the custom size and can take one of the following values:

0.

Inch

1.

Millimeter

2.

Centimeter

3.

Point: 1/72th of an inch

4.

Pixel

The fontsFactor parameter represents a scaling factor for the font sizes of all texts in the plot (the default is 1.0, meaning no scaling). If you set this parameter to 0, the program will automatically try to calculate a scale factor. The compression parameter can be 0 (no compression) or 1 (LZW) and is only effectif for .tif/.tiff images. It is neglected for all other raster image formats.

The function exportTex can be used if you need to export to a TeX file. The escapeStrings parameter enables/disables the escaping of special TeX characters like: $, {, }, ^, etc... If True, the fontSizes parameter triggers the export of the original font sizes in the plot layer. Otherwise all exported text strings will use the font size specified in the preamble of the TeX document.

All the export functions rely on the file name suffix in order to choose the image format.

Arranging Layers

When you are working with many layers in a 2D plot window, setting the layout of these layers manually can be a very tedious task. With the help of a simple Python script you can make this task very easy and automatically manage the layout of the plot window. For example, here's how you can create a two rows by two columns matrix of layers, each plot layer having a canvas size (the drawing area) of 400 pixels wide and 300 pixels in height:

g = newGraph("Test", 4, 2, 2)
g.setLayerCanvasSize(400, 300)
g.arrangeLayers(False, True)
The arrangeLayers()function takes two parameters. The first one specifies if the layers should be arranged automatically, using a best-layout algorithm, or if the numbers of rows and columns is fixed by the user. If the value of the second parameter is True, the size of the canvas is fixed by the user and the plot window will be enlarged or shrunken, according to the user settings. Otherwise the size of the plot window will be kept and the canvas area of each layer will be automatically adapted to fit this size. Here's how you can modify the graph created in the previous example, in order to display a row of three layers, while keeping the size of the plot window unchanged:

g.setNumLayers(3)
g.setRows(1)
g.setCols(3)
g.arrangeLayers(False, False)
By default, the space between two neighboring layers as well as the distance between the layers and the borders of the plot window is set to five pixels. You can change the spacing between the layers and the margins using the following functions:

g.setSpacing (x, y)
g.setMargins (left, right, top, bottom)
Another aspect of the layout management is the alignment of the layers. There are three alignment flags that you can use for the horizontal alignment (HCenter, Left, Right) and another three for the vertical alignment (VCenter, Top, Bottom) of the layers. The following code line aligns the layers with the right edge of the window and centers them vertically in the available space:

g.setAlignement(Graph.Right, Graph.VCenter)
The alignment of the layers can be done with respect to the drawing area between the axes (Graph.AlignCanvases) or with respect to the whole layer widget (Graph.AlignLayers) and you can specify the alignment policy to use via the following method:

g.setAlignPolicy(Graph.AlignCanvases)
A very often needed layout is the one with shared layer axes having linked abscissae (modifying the x scale for one layer will automatically adjust the scales for all plot layers). Here's how you can simply create such a 2x2 layers grid, with only a few lines of code:

g = newGraph("", 4, 2, 2)
g.setSpacing(0, 0)
g.setAlignPolicy(Graph.AlignCanvases)
g.setCommonLayerAxes()
g.arrangeLayers()
g.linkXLayerAxes(True)
All the examples above suppose that the layers are arranged on a grid, but of course you can add layers at any position in the plot window. In the examples below the x, y coordinates, in pixels, refer to the position of the top-left corner of the layer. The origin of the coordinates system coincides with the top-left corner of the plot window, the y coordinate increasing towards the bottom of the window. If the width and height of the layer are not specified they will be set to the default values. The last argument specifies if the default preferences, specified via the Preferences dialog, will be used to customize the new layer (default value is False):

g = newGraph()
l1 = g.addLayer()
l2 = g.addLayer(215, 20)
l3 = g.addLayer(10, 20, 200, 200)
l4 = g.addLayer(10, 20, 200, 200, True)
You can remove a plot layer using:

l = g.layer(num)
g.removeLayer(l)
g.removeActiveLayer()
As you have already seen, in a plot window the active layer is, by default, the last layer added to the plot, but you can change it programatically:

l = g.layer(num)
g.setActiveLayer(l)
In case you need to perform a repetitive task on all the layers in a plot window, you need to use a for loop and of course you need to know the number of layers existing on the plot. Here's a small example showing how to custom the titles of all the layers in the plot window:

g = graph("Graph1")
layers = g.numLayers()
for i in range (1, layers+1):
	l = g.layer(i)
	l.setTitle("Layer"+QtCore.QString.number(i))
	l.setTitleColor(QtGui.QColor("red"))
	l.setTitleFont(QtGui.QFont("Arial", 14, QtGui.QFont.Bold, True))
	l.setTitleAlignment(QtCore.Qt.AlignLeft)
Finally, sometimes it might be useful to be able to swap two layers. This can be done with the help of the following function:

g.swapLayers(layerNum1, layerNum2)

Waterfall Plots

Waterfall plots are ideal for comparing variations between multiple data sets created under similar conditions. A pseudo 3D effect is generated by applying an offset to all the data curves in a 2D plot layer, enabling you to see variations in the Z direction. You can create and customize them using the functions below:

g = waterfallPlot(table("Table1"), (2, 3, 4))
l = g.activeLayer()
l.setWaterfallOffset(50, 20)# x/y offsets as % of the layer drawing area width/height
l.setWaterfallSideLines(True) # draw side lines for all the data curves
l.setWaterfallFillColor(Qt.lightGray)
g.reverseWaterfallOrder() # reverse the order of the displayed curves

3D Plots

Creating a 3D plot

You can plot 3D analytical functions or parametric surfaces. For the 3D functions, the only parameters allowed are xfor the the abscissae values and yfor the ordinates:

g = plot3D("sin(x*y)", -10.0, 10.0, -10.0, 10.0, -2.0, 2.0)
For the parametric surfaces the only parameters allowed are the latitude and the longitude: uand v. Here's, for example, how you can plot a sphere:

g = plot3D("cos(u)*cos(v)", "sin(u)*cos(v)", "sin(v)", -3.14, 3.14, -2, 2)
You can also create 3D height maps using data from matrices and, of course, you can plot table columns:

g = plot3D(matrix("Matrix1"), style = 5)
g = plot3D(table("Table1"), "3", style)
In the case of 3D plots created from matrix data sources the styleparameter can take any integer value from 1 to 5, with the following signification:

1.

Wireframe style

2.

Hidden Line style

3.

Color filled polygons without edges

4.

Color filled polygons with separately colored edges

5.

Scattered points (the default style)

For 3D plots created from tables the styleparameter can take any integer value from 0 to 3 or the equivalent style values from the following list:

0.

Graph3D.Scatter

1.

Graph3D.Trajectory

2.

Graph3D.Bars

3.

Graph3D.Ribbon

An alternative method to create a 3D plot is to create an empty plot window and to assign a data source to it. As you have already seen a data source can be an analytical function, a matrix or a table. For large data sets you can increase the drawing speed by reducing the number of points taken into account. The lower the resolution parameter, the higher the number of points used: for an integer value of 1, all the data points are drawn.

g = newPlot3D("test3D")
g.setTitle("My 3D Plot", QtGui.QColor("blue"), QtGui.QFont("Arial",14))
g.setResolution(2)
g.setFunction("sin(x*y)", -10.0, 10.0, -10.0, 10.0, -2.0, 2.0)
#or
g.setData(table("Table1"), "3")
#or
g.setMatrix(matrix("Matrix1"))
Once a plot is created, you can modify the scales and set the data range to display, using, for example:

g.setScales(-1.0, 1.0, -10.0, 11.0, -2.0, 3.0)

Customizing the view

When a new 3D plot is created, the scene view parameters are set to default values. Of course, QtiPlot provides functions to customize each aspect of the view. For example, you can set rotation angles, in degrees, around the X, Y and Z axes, respectively, using:

g.setRotation(45, 15, 35)
The following function allows you to shift the plot along the world X, Y and Z axes, respectively:

g.setShift(3.0, 7.0, -4.0)
You can also zoom in/out the entire plot as a whole, or you can zoom along a particular axis:

g.setZoom(10)
g.setScale(0.1, 0.05, 0.3)
Also, you can automatically detect the zoom values that fit best with the size of the plot window:

g.findBestLayout()
You can enable/disable the perspective view mode or animate the view using:

g.setOrthogonal(False)
g.animate(True)

Plot Styles

The style of the 3D plot can be set using the following functions:

g.setPolygonStyle()
g.setFilledMeshStyle()
g.showLegend(True)
g.setHiddenLineStyle()
g.setWireframeStyle()
g.setAntialiasing(True)
g.setMeshLineWidth(0.7)
For scatter plots using points you can specify the radius of the points and their shape: circles if smoothis True, rectangles otherwise.

g.setDotOptions(10, smooth = True)
g.setDotStyle()
Other symbols available for scatter plots are: bars

g.setBarRadius(0.01)
g.setBarLines(False)
g.setFilledBars(True)
g.setBarStyle()
cones

g.setConeOptions(radius, quality)
g.setConeStyle()
and crosses (surrounded by a box frame, if boxedis set to True):

g.setCrossOptions(radius, width, smooth, boxed)
g.setCrossStyle()

3D Vectors

It is possible to plot 3D vectors using as data source a table that has at least six columns. The code bellow creates a 3D curve with vector type XYZ dXdYdZ and returns a reference to this curve:

t = table("Table1")
c = newPlot3D().addVectors(t, t.colNames(), True)

The second argument of the addVectors function is a string list that must contain six column names. If the third argument is not specified the type of the 3D vectors is by default set to XYZ XYZ.

Once created the type and the names of the data columns defining the end point of the 3D vector may be changed as shown bellow. The second argument of the setVectorEndZColName function is true in order to reload the data only once (the default value is False):


c.setDxDyDz(False)
c.setVectorEndXColName("Table1_A")
c.setVectorEndYColName("Table1_B")
c.setVectorEndZColName("Table1_C", True)

print c.isDxDyDz()
print c.vectorEndXColName()
print c.vectorEndYColName()
print c.vectorEndZColName()
The appearance of a 3D vectors curve c can be customized using the following functions:

c.setVectorColor(Qt.red)
c.setVectorLineWidth(2.0)
c.setVectorScalingFactor(0.75)

print c.vectorLineWidth()
print c.vectorScalingFactor()
The style of the arrow can be customized using the setArrowStylefunction. The first argument of this function is the head length, the second specifies the value in degrees of the head angle, the third is the quality, that is the number of facets used to draw the arrow head, the forth specifies weather the head is filled or not and the last argument sets the scaling policy for the arrow head. The value of the last argument may be: 0 - no scaling, 1 - logarithmic scaling or 2 - linear scaling.

c.setArrowStyle(0.5, 30, 4, False, 1)

print c.vectorHeadLength()
print c.vectorHeadAngle()
print c.arrowQuality()
print c.hasFilledArrowHead()
print c.vectorScaleHeadPolicy()

The 2D Projection

By default the floor projection of the 3D surface plot is disabled. You can enable a full 2D projection or only display the isolines using the following functions:

g.showFloorProjection()
g.showFloorIsolines()
g.setEmptyFloor()

The Coordinates System

The coordinates system around the surface plot can be customized to display all the twelve axes, only three of them or none, respectively, with the help of the following functions:

g.setBoxed()
g.setFramed()
g.setNoAxes()
If the axes are enabled, you can set their legends and the distance between the legend and the axes via:

g.setXAxisLabel("X axis legend")
g.setYAxisLabel("Y axis legend")
g.setZAxisLabel("Z axis legend")
g.setLabelsDistance(30)
It is possible to set the numerical format and precision of the axes using the function below:

g.setAxisNumericFormat(axis, format, precision)
where the first parameter is the index of the axis: 0 for X, 1 for Y and 2 for Z, the second one is the numerical format:

0.

Graph3D.Default: decimal or scientific, depending which is most compact

1.

Graph3D.Decimal: 10000.0

2.

Graph3D.Scientific: 1e4

3.

Graph3D.Engineering: 10k

and the last parameter is the precision (the number of significant digits). The following convenience functions are also provided, where you don't have to specify the index of the axis anymore:

g.setXAxisNumericFormat(1, 3)
g.setYAxisNumericFormat(1, 3)
g.setZAxisNumericFormat(1, 3)
Also, you can fix the length of the major and minor ticks of an axis:

g.setXAxisTickLength(2.5, 1.5)
g.setYAxisTickLength(2.5, 1.5)
g.setZAxisTickLength(2.5, 1.5)

Grid

If the coordinate system is displayed, you can also display a grid around the surface plot. Each side of the grid can be shown/hidden:

g.setLeftGrid(True)
g.setRightGrid()
g.setCeilGrid()
g.setFloorGrid()
g.setFrontGrid()
g.setBackGrid(False)

Customizing the Plot Colors

The default color map of the plot is defined using two colors: red for the maximum data values and blue for the minimum data values. You can change these default colors:

g.setDataColors(QtCore.Qt.black, QtCore.Qt.green)
g.update()
Of course, you can define more complex color maps, using LinearColorMapobjects:

map = LinearColorMap(QtCore.Qt.yellow, QtCore.Qt.blue)
map.setMode(LinearColorMap.FixedColors) # default mode is LinearColorMap.ScaledColors
map.addColorStop(0.2, QtCore.Qt.magenta)
map.addColorStop(0.7, QtCore.Qt.cyan)
g.setDataColorMap(map)
g.update()
Also, you can use predefined color maps stored in .map files. A .map file consists of a of 255 lines, each line defining a color coded as RGB values. A set of predefined color map files can be downloaded from QtiPlot web site, in the "Miscellaneous" section.

g.setDataColorMap(fileName)
g.update()
The colors of all the other plot elements can be customized as shown below. Don't forget to update the plot in order to display the new colors:

g.setMeshColor(QtGui.QColor("blue"))
g.setAxesColor(QtGui.QColor("green"))
g.setNumbersColor(QtGui.QColor("black"))
g.setLabelsColor(QtGui.QColor("darkRed"))
g.setBackgroundColor(QtGui.QColor("lightYellow"))
g.setGridColor(QtGui.QColor("grey"))
g.setDataColors(QtGui.QColor("red"), QtGui.QColor("orange"))
g.setOpacity(0.75)
g.update()

Exporting

In order to export a 3D plot you need to specify a file name containing a valid file format extension:

g.export(fileName)
This function uses some default export options. If you want to customize the exported image, you should use the following function in order to export to raster image formats:

g.exportImage(fileName, int quality = 100, bool transparent = False, dpi = 0, size = QSizeF(), unit = Frame.Pixel, fontsFactor = 1.0, compression = 0)
where qualityis a compression factor: the larger its value, the better the quality of the exported image, but also the larger the file size. The dpiparameter represents the export resolution in pixels per inch (the default is screen resolution), sizeis the printed size of the image (the default is the size on screen) and unitis the length unit used to express the custom size and can take one of the following values:

0.

Inch

1.

Millimeter

2.

Centimeter

3.

Point: 1/72th of an inch

4.

Pixel

The fontsFactorparameter represents a scaling factor for the font sizes of all texts in the plot (the default is 1.0, meaning no scaling). If you set this parameter to 0, the program will automatically try to calculate a scale factor. The compressionparameter can be 0 (no compression) or 1 (LZW) and is only effectif for .tif/.tiff images. It is neglected for all other raster image formats.

3D plots can be exported to any of the following vector formats: .eps, .ps, .pdf, .pgf and .svg, using the function below:


g.exportVector(fileName, textMode = 0, sortMode = 1, size = QSizeF(), unit = Frame.Pixel, fontsFactor = 1.0)
where textMode is an integer value, specifying how texts are handled. It can take one of the following values:

0.

All text will be converted to bitmap images (default).

1.

Text output in the native output format.

2.

Text output in additional LaTeX file as an overlay.

The sortMode parameter is also an integer value and can take one of the following values:

0.

No sorting at all.

1.

A simple, quick sort algorithm (default).

2.

BSP sort: best algorithm, but slow.

The other parameters have the same meaning as for the export of 2D plots.

Data Analysis

General Functions

As you will see in the following subsections, the data analysis operations available in QtiPlot are: convolution/deconvolution, correlation, differentiation, FFT, filtering, smoothing, fitting and numerical integration of data sets. Generally, you can declare/initialize an analysis operation using one of the following methods, depending on the data source, which can be a 2D plot curve or a table:

op = LogisticFit(graph("Graph1").activeLayer().curve(0), 15.2, 30.9)
op = FFTFilter(graph("Graph1").activeLayer(), "Table1_2", 1.5, 3.9)
op = LinearFit(table("Table1"), "colX", "colY", 10, 100)
In the first example the data source is a curve Table1_2, plotted in the active layer of the graph Graph1and the abscissae range is chosen between 1.5 and 3.9. In the second example the data source is a table Table1. The abscissae of the data set are stored in the column called colXand the ordinates in the column colY. The data range is chosen between the 10th row and the row with the index 100. If you don't specify the row range, by default the whole table will be used. Not all operations support curves as data sources, like for example: convolution/deconvolution and correlation. For these operations only table columns can be used as data sources for the moment.

Once you have initialized an operation, you can still change its input data via the following functions:


op.setDataFromCurve(graph("Graph2").activeLayer().curve(1), 10.5, 20.1)
op.setDataFromCurve("Table1_energy", 10.5, 20.1, graph("Graph2").activeLayer())
op.setDataFromTable(table("Table1"), "colX", "colY", 10, 100)
You don't have to specify a plot layer in the setDataFromCurve() function, if the analysis operation has already been initialized by specifying a curve on an existing graph and you just want to treat another curve from the same plot layer.

Also, when performing analysis tasks via Python scripts, there are several utility functions that can be called for all operations. For example you can disable any graphical output from an operation or you can redirect the output to the plot layer of your choice:


op.enableGraphicsDisplay(False)
op.enableGraphicsDisplay(True, graph("Graph2").activeLayer())
Let's assume that you need to perform a specific operation op, which analyzes your data and at the end, displays a result curve. For this kind of operations, you can customize the number of points in the resulting curve and its color:

op.setOutputPoints(int)
op.setColor(int)
op.setColor("green")
Colors can be specified by their names or as integer values, from 0 to 23, each integer corresponding to a predefined color: 0 - "black", 1 - "red", 2 - "green", 3 - "blue", 4 - "cyan", 5 - "magenta", 6 - "yellow", 7 - "darkYellow", 8 - "navy", 9 - "purple", etc ...

Most of the time, a new table is also created as a result of a data analysis operation. This table stores the data displayed by the result curve and is hidden by default, but you can interact with it via the following function:


t = op.resultTable()

After the initialization of an analysis operation, which consists of setting the data source, the data range and some other properties, like color, number of points, etc..., you can execute it via a call to its run() function:

op.run()
For data fitting operations, there's an alias for the run() function which is: fit().

Correlation, Convolution/Deconvolution

Assuming you have a table named "Table1", here's how you can calculate the convolution of two of its columns, "Table1_B" and "Table1_C":

conv = Convolution(table("Table1"),  "B", "C")
conv.setColor("green")
conv.run()
The deconvolution and the correlation of two data sets can be done using a similar syntax:

dec = Deconvolution(table("Table1"),  "B", "C")
dec.run()

cor = Correlation(table("Table1"),  "B", "C", 10, 200)
cor.setColor("green")
cor.run()

Differentiation

Assuming you have a Graph named "Graph1" containing one curve (on its active layer), here's how you can differentiate this curve within a defined x interval, [2,10] in this case:

diff = Differentiation(graph("Graph1").activeLayer().curve(0), 2, 10)
diff.run()
The result of these code sequence would be a new plot window displaying the derivative of the initial curve. The numerical derivative is calculated using a five terms formula.

FFT

Assuming you have a graph named "Graph1" containing one curve on its active layer and having a periodicity of 0.1 in the time domain, a FFT will allow you to extract its characteristic frequencies. The results will be stored in a hidden table named "FFT1".

fft = FFT(graph("Graph1").activeLayer().curve(0))
fft.normalizeAmplitudes(False)
fft.shiftFrequencies(False)
fft.setSampling(0.1)
fft.run()
By default the calculated amplitudes are normalized and the corresponding frequencies are shifted in order to obtain a centered x-scale. If we want to recover the initial curve with the help of the inverse transformation, we mustn't modify the amplitudes and the frequencies. Also the sampling parameter must be set to the inverse of the time period, that is 10. Here's how we can perform the inverse FFT, using the "FFT1" table, in order to recover the original curve:

ifft = FFT(table("FFT1"), "Real", "Imaginary")
ifft.setInverseFFT()
ifft.normalizeAmplitudes(False)
ifft.shiftFrequencies(False)
ifft.setSampling(10)
ifft.run()
You can also perform 2D fast Fourrier transforms on matrices. The FFT routine takes in this case the following parameters: rm- specifies the real part input matrix, im- specifies the imaginary part input matrix, inverse- specifies the direction of the FFT, DCShift- if this is true, the DC component will be put in the center of the result matrix, otherwise, the DC component will locate at four corners of the result matrix, norm- specifies whether or not to normalize the amplitudes to 1, outputPower2Sizes- forces output matrices whose sizes are integer powers of 2 (zero padding is used to initialize the missing cells)

fft = FFT(Matrix *rm, Matrix *im = NULL, bool inverse = False, bool DCShift = True, bool norm = False, bool outputPower2Sizes = True)
Here's how you can perform the 2D FFT of a matrix called "Matrix1", and the inverse FFT in order to recover the original image:

from qti import *
m = matrix("Matrix1")
m.setViewType(Matrix.ImageView) # make sure the matrix is displayed as image

fft = FFT(m)
fft.run()
fft.amplitudesMatrix().resize(500, 400)

rMatrix = fft.realOutputMatrix()
rMatrix.hide()
iMatrix = fft.imaginaryOutputMatrix()
iMatrix.hide()

ifft = FFT(rMatrix, iMatrix, True)
ifft.run()
ifft.realOutputMatrix().hide()
ifft.imaginaryOutputMatrix().hide()

FFT Filters

In this section, it will be assumed that you have a signal displayed in a graph ("Graph1", on its active layer). This signal has a power spectrum with high and low frequencies. You can filter some of these frequencies according to your needs, using a FFTFilter. Here's how you can cut all the frequencies lower than 1 Hz:

filter = FFTFilter(graph("Graph1").activeLayer().curve(0), FFTFilter.HighPass)
filter.setCutoff(1)
filter.run()
Here's how you can cut all the frequencies lower than 1.5 Hz and higher than 3.5 Hz. In the following example the continuous component of the signal is also removed:

filter.setFilterType(FFTFilter.BandPass)
filter.enableOffset(False)
filter.setBand(1.5, 3.5)
filter.run()
Other types of FFT filters available in QtiPlot are: low pass (FFTFilter.LowPass) and band block (FFTFilter.BandBlock).

Fitting

Assuming you have a graph named "Graph1" displaying a curve entitled "Table1_2" on its active layer, a minimal Fit example would be:

f = GaussFit(graph("Graph1").activeLayer().curve(0))
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(curve)

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

  • ExponentialFit(curve, growth=False)

  • TwoExpFit(curve)

  • ThreeExpFit(curve)

  • GaussFit(curve)

  • GaussAmpFit(curve)

  • LorentzFit(curve)

  • LogisticFit(curve)

  • SigmoidalFit(curve)

  • PsdVoigt1Fit(curve)

  • PsdVoigt2Fit(curve)

  • MultiPeakFit(curve, xStart, xEnd, profile=MultiPeakFit.Gauss, peaks=1)

    
f = MultiPeakFit(graph("Graph1").activeLayer().curve(0),100,900,MultiPeakFit.PsdVoigt1,3)
    f.guessInitialValues()
    f.setPeakCurvesColor(Qt.green)
    f.generateFunction(True, 1000)
    f.run()
    			
    The following profile functions are available: Gauss, Lorentz, PsdVoigt1and PsdVoigt2.
  • NonLinearFit(curve)

    
f = NonLinearFit(layer, curve)
    f.setFormula(formula_string)
    f.save(fileName)
    			
  • PluginFit(curve)

    
f = PluginFit(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().curve(0), 2, 7)
f.fit()
	  
You can also restrict the search range for any of the fit parameters:

f = NonLinearFit(graph("Graph1").activeLayer().curve(0))
f.setFormula("a0+a1*x+a2*x*x")
f.setParameterRange(parameterIndex, start, end)
All the settings of a non-linear fit can be saved to an XML file and restored later one, using this file, for a faster editing process. Here's for example how you can save the above fit function:

f.save("/fit_models/poly_fit.txt")
and how you can use this file during another fitting session, later on:

f = NonLinearFit(graph("Graph1").activeLayer(), "Table1_2")
f.load("/fit_models/poly_fit.txt")
f.fit()
If your script relies on a specific numbering of the fit parameters use setParameters() before setting the formula and switch of automatic detection of the fit parameters when the fit formula is set:

f.setParameters("a2","a0","a1")
f.setFormula("a0+a1*x+a2*x*x",0)

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


f.setDataFromTable(table("Table4"), "w", "energy", 10, 200, True) #change data source (last parameter enables/disables data sorting)
f.setDataFromCurve(curve)			#change data source
f.setDataFromCurve(curveTitle, graph)		#change data source
f.setDataFromCurve(curve, from, to)		#change data source
f.setDataFromCurve(curveTitle, 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.setWeightingData(method, colname) # method = Fit.NoWeighting, Fit.Instrumental, Fit.Statistical, Fit.Dataset, Fit.Direct
f.setTolerance(tolerance)
f.setOutputPrecision(precision)
f.setMaximumIterations(number)
f.scaleErrors(yes = True)
f.setColor("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.residuals()
f.dataSize()
f.numParameters()
f.parametersTable("params")
f.covarianceMatrix("cov")
Writing the fit results to log is a time consuming operation and, especially when you need to perform a large number of fits, you can disable/enable this functionality using:

setWriteFitResultsToLog(False) # the boolean parameter of this method is True by default
There are a number of statistical functions allowing you to test the goodness of the fit:

f.chiSquare()
f.rSquare()
f.adjustedRSquare()
f.rmse() # Root Mean Squared Error
f.rss()  # Residual Sum of Squares
Also you can display the confidence and the prediction limits for the fit, using a custom confidence level:

f.showPredictionLimits(0.95)
f.showConfidenceLimits(0.95)
Confidence limits for individual fit parameters can be calculated using:

f.lcl(parameterIndex, confidenceLevel)
f.ucl(parameterIndex, confidenceLevel)
where parameterIndexis a value between zero and f.numParameters() - 1.

It is important to know that QtiPlot can generate an analytical formula for the resulting fit curve or a normal plot curve with data stored in a hidden table. You can choose either of these two output options, before calling the fit() instruction, using:


f.generateFunction(True, points=100)

If the first parameter of the above function is set to True, QtiPlot will generate an analytical function curve. If the points parameter is not specified, by default the function will be estimated over 100 points. You can get the analytical formula of the fit curve via a call to resultFormula():

formula = f.resultFormula()
print(formula)
If the first parameter of generateFunction() is set to False, QtiPlot will create a hidden data table containing the same number of points as the data set/curve to be fitted (same abscissae). You can interact with this table and extract the data points of the result fit curve using:

t = f.resultTable()

Integration

With the same assumptions as above, here's how you can integrate a curve within a given interval:

integral = Integration(graph("Graph1").activeLayer().curve(0), 2, 10)
integral.run()
result = integral.area()
The script bellow shows how to perform an integration on a data set from a table:

i = Integration(table("Table1"), "Table_1", "Table_2", 3, 20, True)# sorted data range from row 3 to 20
i.enableGraphicsDisplay(False)
i.run()
result = i.area()

As you can see from the above examples, the numerical value of the integral can be obtained via the area() function.

Interpolation

The interpolation is used to generate a new data curve with a high number of points from an existing data set. Here's an example:

interpolation = Interpolation(graph("Graph1").activeLayer().curve(0), 2, 10, Interpolation.Linear)
interpolation.setOutputPoints(10000)
interpolation.setColor("green")
interpolation.run()
The simplest interpolation method is the linear method. There are two other methods available: Interpolation.Akimaand Interpolation.Cubic. You can choose the interpolation method using:

interpolation.setMethod(Interpolation.Akima)
It is possible to evaluate the resulting spline at a certain x value:

print interpolation.evalAt(1.5)
The script bellow shows how to perform an interpolation on a data set from an existing table using all three available methods. The script also creates a plot of the original data set together with the interpolated splines:

t = table("Table1") # existing source data table
t2 = newTable(50, 4) # we create an output table

interpol = Interpolation(t, "Table1_1", "Table1_2", Interpolation.Linear)
for i in range (1, t2.numRows() + 1):
	x = 0.05*i
	t2.setCellData(1, i, x)
	t2.setCellData(2, i, interpol.evalAt(x))

interpol.setMethod(Interpolation.Cubic)
for i in range (1, t2.numRows() + 1):
	t2.setCellData(3, i, interpol.evalAt(0.05*i))

interpol.setMethod(Interpolation.Akima)
for i in range (1, t2.numRows() + 1):
	t2.setCellData(4, i, interpol.evalAt(0.05*i))

g = qti.app.plot(t, 2, Layer.LineSymbols).activeLayer() # plot input data set
g.addCurves(t2, (2, 3, 4), Layer.Line) # add interpolated splines to the plot layer

Smoothing

Assuming you have a graph named "Graph1" with an irregular curve entitled "Table1_2" (on its active layer). You can smooth this curve using a SmoothFilter:

smooth = SmoothFilter(graph("Graph1").activeLayer().curve(0), SmoothFilter.Average)
smooth.setSmoothPoints(10)
smooth.run()
The default smoothing method is the mowing window average. Other smoothing methods are the SmoothFilter.FFT, SmoothFilter.Lowessand SmoothFilter.SavitzkyGolay. Here's an example of how to use the last two methods:

smooth.setMethod(SmoothFilter.Lowess)
smooth.setLowessParameter(0.2, 2)
smooth.run()

smooth.setSmoothPoints(5,5)
smooth.setMethod(SmoothFilter.SavitzkyGolay)
smooth.setPolynomOrder(9)
smooth.run()

Statistics

Descriptive Statistics


stats = Statistics("Table1_2")
stats.run()

print stats.mean()
print stats.variance()
print stats.standardDeviation()
print stats.standardError()
For all the statistic test below, once you have created a test object, you can use the following methods:

test.showResultsLog(False) # disable the logging of the results
test.showDescriptiveStatistics(False) # disable the display of the descriptive statistics results
test.run()

print test.statistic()
print test.pValue()
print test.logInfo()

t = test.resultTable("MyResultTable") # Returns a pointer to the table created to display the results (the table name is optional)

Hypothesis Testing - Student's t-Test


test = tTest(15.2, 0.05, "Table1_2") # One sample test, test mean = 15.2, significance level = 0.05
test.run()

test.setTestValue(15.0)
test.setSignificanceLevel(0.5)
test.setTail(tTest.Left) # or tTest.Right, or tTest.Both (default value)
test.run()

print test.t() # same as test.statistic()
print test.dof() # degrees of freedom
print test.power(0.5)
print test.power(0.5, 50) # alternative sample size = 50
print test.pValue()
print test.lcl(90) # lower confidence limit for mean
print test.ucl(90) # upper confidence limit for mean

test = tTest(15.2, 0.05, "Table1_1", "Table1_2", True) # Two sample paired test
print test.logInfo()

test = tTest(15.2, 0.05, "Table1_1", "Table1_2") # Two sample independent test
test.run()

test.setSample1("Table2_1")
test.setSample2("Table3_2", True) # Two sample paired test
test.run()

One Sample Test for Variance (Chi-Square Test)


test = ChiSquareTest(88.2, 0.05, "Table1_2") # Test variance = 88.2, significance level = 0.05
test.run()

print test.chiSquare() # same as test.statistic()
print test.pValue()
print test.logInfo()

Normality Test (Shapiro - Wilk)


test = ShapiroWilkTest("Table3_1")
test.setSignificanceLevel(0.1)
test.run()

print test.w() # same as test.statistic()
print test.pValue()
print test.logInfo()

One-Way ANOVA

Please read the documentation of the TAMUANOVA libraryfor more details.

test = Anova()
test.setSignificanceLevel(0.1) # default level is 0.05
test.addSample("Table1_1");
test.addSample("Table1_2");
test.addSample("Table1_3");
test.run()

print test.fStat() # F statistic = ssm/sse (same as test.statistic())
print test.pValue()
print test.ssm() # "between-group" sum of squares
print test.sse() # "within-group" sum of squares
print test.sst() # total sum of squares

test.showDescriptiveStatistics(False)
print test.logInfo()

Two-Way ANOVA

Please read the documentation of the TAMUANOVA libraryfor more details.

test = Anova(True)
test.addSample("Table1_1", 1, 1) # Level factor A = 1, level factor B = 1
test.addSample("Table1_2", 1, 2) # Level factor A = 1, level factor B = 2
test.addSample("Table1_3", 2, 1) # Level factor A = 2, level factor B = 1
test.addSample("Table1_4", 2, 2) # Level factor A = 2, level factor B = 2
test.setAnovaTwoWayModel(2) # Fixed model = 0, Random model = 1, Mixed model = 2
test.run()

print test.fStatA() # F statistic for factor A
print test.fStatB() # F statistic for factor B
print test.fStatAB() # F statistic for the interaction
print test.pValueA() # P value for factor A
print test.pValueB() # P value for factor B
print test.pValueAB() # P value for the interaction
print test.ssa() # sum of squares for factor A
print test.ssb() # sum of squares for factor B
print test.ssab() # sum of squares for the interaction
print test.msa() # mean square value for factor A
print test.msb() # mean square value for factor B
print test.msab() # mean square value for the interaction

print test.logInfo()

Working with Notes

The following functions are available when dealing with multi-tab notes:


setAutoexec(on = True)

text()
setText(text)

exportPDF(fileName)
saveAs(fileName)
importASCII(fileName)

showLineNumbers(on = True)

setFont(QFont f)
setTabStopWidth(int length)

tabs()
addTab()
removeTab(tabIndex)
renameTab(tabIndex, title)

e = editor(int index)
e = currentEditor()
It is possible to trigger the execution of a script in a Notes window tab:

e = note("Notes1").currentEditor()
e.executeAll()
# Check if the script is still running:
print e.isRunning()
It is also possible to program a script to be run periodically:

e = note("Notes1").currentEditor()
e.executePeriodically(3.5) # running interval is set to 3.5 seconds
print e.isRunningPeriodically() # should print True
print e.runningInterval() # should print 3.5
In order to stop the periodic execution of a script you may use:

note("Notes1").currentEditor().stopPeriodicExecution()

Using PyQt's dialogs and classes

Let's assume that you have a lot of ASCII data files to analyze. Furthermore, let's suppose that these files were created during several series of measurements, each measurement generating a set of files identified by a certain string in the file name, like for example: "disper1". In order to analyze these files, you need first of all to import them into tables. The following code snippet shows how to automate this task using PyQt dialogs and convenience classes:

# Pop-up a file dialog allowing to chose the working folder:
dirPath = QFileDialog.getExistingDirectory(qti.app, "Choose Working Folder", "/test/")
# Create a folder object using Qt's QDir class:
folder = QDir(dirPath)
# Pop-up a text input dialog allowing to chose the file naming pattern:
namePattern,ok = QInputDialog.getText(qti.app,"Pattern","Text:",QLineEdit.Normal,"disper1")
if ok: # get the list of file names in the working directory containing the above pattern
	fileNames = folder.entryList(QStringList ("*" + namePattern + "*.dat"))
	for i in range (0, fileNames.count()): # import each file into a new project table
		newTable().importASCII(dirPath + "/" + fileNames[i],";")
For a detailed description of all the dialogs and utility classes provided by Qt/PyQt please take a look at the PyQt documentation.

Using Qt Designer for easy creation of custom user dialogs

Writing and designing user dialogs can be a very complicated task. The QtDesigner application provided by the Qt framework makes it easy and very pleasant. It allows you to design widgets, dialogs or complete main windows using on-screen forms and a simple drag-and-drop interface. Qt Designer uses XML .ui files to store designs. Once you have finished the design process you can load and use an .ui file in your Python scripts with the help of the uicmodule.

As an example, suppose that we have created a test dialog containing an input QDoubleSpinBox called "valueBox" and a QPushButton called "okButton". On pressing this button, we would like to create a new table displaying the input value in its first cell. We have saved this dialog to a file called "myDialog.ui". A minimalistic approach is shown in the small script below:


def createTable():
	t = newTable()
	t.setCell(1, 1, ui.valueBox.value())

ui = uic.loadUi("myDialog.ui")
ui.connect(ui.okButton, QtCore.SIGNAL("clicked()"), createTable)
ui.show()
For more details about how to use .ui files in your Python scripts please read the PyQt documentation.

Task automation example

Below you can find a detailed example showing how to completely automatize tasks in QtiPlot. It can be used in order to verify the accuracy of the curve fitting algorithms in QtiPlot. The data used in this example is retrieved from the Statistical Reference Datasets Project of the National Institute of Standards and Technology (NIST). In order to run this example, you need an internet connection, since the script will try to download all the nonlinear regression test files from the Statistical Reference Datasets Project.

import urllib, re, sys

# Pop-up a file dialog allowing to chose a destination folder:
dirPath = QtGui.QFileDialog.getExistingDirectory(qti.app, "Choose Destination Folder")

saveout = sys.stdout
# create a log file in the destination folder
fsock = open(dirPath + "/" + "results.txt", "w")
sys.stdout = fsock

# on Unix systems you can redirect the output directly to a console by uncommenting the line below:
#sys.stdout = sys.__stdout__

# make sure that the decimal separator is the dot character
qti.app.setLocale(QtCore.QLocale.c())

host = "http://www.itl.nist.gov/div898/strd/nls/data/LINKS/DATA/"
url = urllib.urlopen(host)
url_string = url.read()
p = re.compile( '\w{,}.dat">' )
iterator = p.finditer( url_string )
for m in iterator:
	name = (m.group()).replace("\">", "")
	if (name == "Nelson.dat"):
		continue

	url = host + name
	print  "\nRetrieving file: " + url
	path = dirPath + "/" + name
	urllib.urlretrieve( url, path ) # retrieve .dat file to specified location

	file = QtCore.QFile(path)
	if file.open(QtCore.QIODevice.ReadOnly):
		ts = QtCore.QTextStream(file)
		name = name.replace(".dat", "")
		changeFolder(addFolder(name)) #create a new folder and move to it
		formula = ""
		parameters = 0
		initValues = list()
		certifiedValues = list()
		standardDevValues = list()
		xLabel = "X"
		yLabel = "Y"

		while (ts.atEnd() == False):
			s = ts.readLine().simplified()

			if (s.contains("(y = ")):
				lst = s.split("=")
				yLabel = lst[1].remove(")")

			if (s.contains("(x = ")):
				lst = s.split("=")
				xLabel = lst[1].remove(")")

			if (s.contains("Model:")):
				s = ts.readLine().simplified()
				lst = s.split(QtCore.QRegExp("\\s"))
				s = lst[0]
				parameters = s.toInt()[0]
				ts.readLine()
				if (name == "Roszman1"):
					ts.readLine()
					formula = ts.readLine().simplified()
				else:
					formula = (ts.readLine() + ts.readLine() + ts.readLine()).simplified()
				formula.remove("+ e").remove("y =").replace("[", "(").replace("]", ")")
				formula.replace("**", "^").replace("arctan", "atan")

			if (s.contains("Starting")):
				ts.readLine()
				ts.readLine()
				for i in range (1, parameters + 1):
					s = ts.readLine().simplified()
					lst = s.split(" = ")
					s = lst[1].simplified()
					lst = s.split(QtCore.QRegExp("\\s"))
					initValues.append(lst[1])
					certifiedValues.append(lst[2])
					standardDevValues.append(lst[3])

			if (s.contains("Data: y")):
				row = 0
				t = newTable(name, 300, 2)
				t.setColName(1, "y")
				t.setColumnRole(1, Table.Y)
				t.setColName(2, "x")
				t.setColumnRole(2, Table.X)
				while (ts.atEnd() == False):
					row = row + 1
					s = ts.readLine().simplified()
					lst = s.split(QtCore.QRegExp("\\s"))
					t.setText(1, row, lst[0])
					t.setText(2, row, lst[1])

				g = plot(t, t.colName(1), Layer.Scatter).activeLayer()
				g.setTitle("Data set: " + name + ".dat")
				g.setAxisTitle(Layer.Bottom, xLabel)
				g.setAxisTitle(Layer.Left, yLabel)

				f = NonLinearFit(g, name + "_" + t.colName(1))
				if (f.setFormula(formula) == False) :
					file.close()
					changeFolder(rootFolder())
					continue

				f.scaleErrors()
				for i in range (0, parameters):
					f.setInitialValue(i, initValues[i].toDouble()[0])
				f.fit()
				g.removeLegend()
				f.showLegend()
				print  "QtiPlot Results:\n" + f.legendInfo()

				print  "\nCertified Values:"
				paramNames = f.parameterNames()
				for i in range (0, parameters):
					print  '%s = %s +/- %s' % (paramNames[i], certifiedValues[i], standardDevValues[i])

				print  "\nDifference with QtiPlot results:"
				results = f.results()
				for i in range (0, parameters):
					diff = fabs(results[i] - certifiedValues[i].toDouble()[0])
					print  'db%d = %6g' % (i+1, diff)

				file.close()
				changeFolder(rootFolder())

newNote("ResultsLog").importASCII(dirPath + "/" + "results.txt")
saveProjectAs(dirPath + "/" + "StRD_NIST.qti")
sys.stdout = saveout
fsock.close()

Scope Changes

In recent versions the scope rules were changed to match standard Python:

If a script has any "global" declaration outside of a function, QtiPlot uses the old scope rules. Existing scripts should keep working, but for best results, update your scripts:

QtiPlot/Python API

The complete QtiPlot/Python API can be consulted here.

PyQt Class Reference

The complete PyQt class reference can be consulted here.