Writing Jython Scripts

Data can be processed or accessed in the Python window of FireCode.   The internal data is in the form of Java objects, which might have been created by either Java source code or Scala source code.   In either case, the fields of an object are generally extracted as obj.field() and the methods are used as obj.method( input1, input2, ...).  

In the text below, the notation [x] means an array of objects of type x.   A function call foo( x, y, z="abc") means that arguments x and y must be given, but z can be skipped and a default value of "abc" will be used instead.

The Java objects of FireCode can be accessed directly in Python.  The most common objects (workspace, experiment, plate, FCS record, analysis object) have Python wrappers to simplify access.   

Pointers to examples are given at the end. 

A PyExperiment hides any details of how the the particles were calculated.   It shows the same data whether it came from the original FCS file or from a saved FWS file.   To get more detailed particle calling and decoding data, use a PyParticles object.

The wrapper objects will be defined shortly.   The following functions generate them.

For example, to proceed from raw images to a decoded experiment

fcss=loadImages( "myfolder/tiffs", "output")
e=fcs2experiment( fcss, "panel.plx", "Experiment1")

Object PyExperiment defines the samples and probes and data in an experiment, and is the most common way of dealing with data unless detailed decoding information is needed.   It is created either using PyExperiment( e) where e is an existing Java Experiment, or using the fcs2experiment function.   It has the fields and methods

Object PyWorkspace wraps a Java workspace and contains fields
Object PyFCS encapsulates the FCS data of a well (even if it originated as FCI)
Object PyParticles defines the particles in a well.


Plots are built by assembling pieces, like an axis plus a set of lines plus a set of dots, etc.   The function plot is then called on the list of pieces.   For example,
plot( axes("samples","signal","data for experiment 2", log="xy")+
    scatter( xs, ys, log="xy"),
    lines( xs2, ys, log="xy")

Functions are

GUI programming

Interactive GUI functions can be built using a set of wrappers above the underlying components from Java's Swing library, including JButton, JCheckbox, JLabel, JFrame, JPanel, JTextBox.   A full discussion of Swing is beyond the scope of this document, but in a nutshell there are components, which are laid out in panels, and the panels are shown in a frame.   The wrapper functions defined by FireCode are

Excel reports

PyXLSX is an Excel wrapper  built using python dictionaries.  Each sheet has a dictionary with entries for A01, A02, etc.   There is also a style for each cell.   Cell A01 in sheet Sheet1 in the spreadsheet object xl is referenced as xl.dicts["Sheet1"]["A01"], and its style is xl.styles["Sheet1"]["A01"].
The following functions are defined:

Styles are built by starting with a default and then updating.   This makes it (slightly) less painful to style a table, since it is not necessary to build a different style for each side, each corner, and each interior cell, as one would otherwise have to do.   The operations that can be performed on a style are

Example: xl.updstyleref("S1","A01", lambda x: x.setBorder("right","m--",Color.blue))

Built-in variables

These variables are built into the interpreter

Built-in functions

These functions are built into the interpreter, or are part of the standard library.



Arrays are compatible between Python and Java, but other collections like List, Seq, Vector in Java have no equivalent in Python.   Most functions in FireCode deal with Seq[Object] so it is often necessary to switch back and forth when extracting something from FireCode or feeding data back to FireCode.   To get the length of a Python array, use len( array).   For a Firecode vector of any kind, the corresponding function is array.size().

Numerical functions

Error Handling

In Firecode, many functions that might result in a value but which might fail are returned as a Vali[Object] which can contain either Valid( result) or an error message.

Typical usage would be
if( vget(xv) != None):
    do something with vget(xv)
    println( "HELP: "+ verr( xv))


The standard python library itself is in the .firecode/python folder of your home folder (after you run the python interpreter for the first time).   The code for the functions and objects above can be found there and is the ultimate reference.   In addition, there are some large examples there in the files with names starting 6 and above, demonstrating how to create GUIs and Excel files using tables and graphs calculated from data.   Smaller examples can be found found on the manufacturing server.


Syntax errors and runtime errors are shown in the lower half of the input window. 

Python syntax errors are listed with the line number corresponding to the position in the input window, with the lines numbered starting at 1.   For scripts longer than a few lines, it is worth saving the script to file and using a text editor (Notepad++, Emacs) to edit the file, especially to make sure parentheses and square brackets are matched.

Mysterious errors referring to "instancemethod" almost always mean there should have been parentheses after a name.  For instance, sample.name should be sample.name(), because name() is actually a method of the object sample, not a field.

See Also

Help Front Page