Subsections
Using third party functions in SciCraft
This section deals with integrating your own functions or tool boxes to SciCraft. To be
able to do so, SciCraft must support the programs associated with the language you write
the function in. SciCraft currently supports the following: Octave, R and Python. To be
able to integrate the functions in SciCraft, you sometimes have to follow certain
guidelines when writing the functions. See section 2.4.1 for further
information.
Making your functions accessable in SciCraft is done by creating a XML-file (refered to as
zml files). This is usually done by using the built on ZMLCreator that you will find on
the File menu, see section 2.4.2. If your files are located
in another location than
path-to-scicraft
/Functions, you have to add the path to
the path list that SciCraft searches through when adding all the functions. This is done
by adding the path via the SciCraft loadpath form (section 2.3.3).
Your function scripts may print text to the screen when they are run.
This output will not be visible in your terminal when you run the
function under SciCraft. Instead the output will be collected when the
function is executed, and the output is available by right-clicking
the function node, and selecting Show function output (see
section 2.2.11 for further details).
Writing functions for SciCraft
Currently, R, Octave and Python functions are accepted by SciCraft. Octave is
very similar to MatlabTM, so users who know MatlabTM
should easily be able to port their functions to Octave. In most cases, no
changes are neccessary. As SciCraft is an open source project, we assume users
will contribute by writing plugins for other appropriate systems as well.
SciCraft should be able to handle all R functions with some modifications. When writing
functions in R, you have to have a return statement which creates names for each returned
value. This can be done by using the following statement:
return(list(name1=val1, name2=val2, ... , nameN=valN))
Example:
mlr <- function(formula,rawdata)
{
c <- lm(as.formula(formula),rawdata)
return(list(mlrdata=c))
}
When importing a Python function into SciCraft there are a few things to keep in mind.
- The function node you create needs both an input and an output port
- The input port(s) that you create has to have the same name(s) as the parameters
in your python function.
- All import statements have to be done inside the python functions
- You can only return one variable from your function. If you need to return more
than one variable, add these to a dictionary that you return as your result.
Below is a short example of a python function and a ZML description of this function:
def test(number1, number2):
import math
result = {}
result1 = math.sin(number1)
result2 = sunNumber * number2
result[``result1''] = result1
result[``result2''] = result2
return result
<function>
<title>test</title>
<filename>test.py</filename>
<description>Just a short test</description>
<plugin>PythonPlugin</plugin>
<input>
<port>
<name>input1</name>
<type></type>
<description></description>
</port>
<port>
<name>input2</name>
<type></type>
<description></description>
</port>
</input>
<output>
<port>
<name>result1</name>
<type></type>
<description></description>
</port>
<port>
<name>result2</name>
<type></type>
<description></description>
</port>
</output>
</function>
Importing functions into SciCraft
To use a function in SciCraft, you will need a zml file which describes the
function. These can either be created manually, or by using the supplied
ZMLCreator (Figure 2.19). Be warned that SciCraft may not start
correctly if it encounters bad zml files. The ZMLCreator can be started through
the SciCraft file menu. The text field at the bottom of the screen will show
what the zml will look like when saved.
Figure 2.19:
The ZMLCreator.
![\begin{figure}\begin{center}
\includegraphics[scale=0.5]{zmlcreator.eps}\end{center}\end{figure}](node_img25.png) |
One of the easiest ways to understand what the different variables mean, and how
they work, may be to look at the already existing functions. If you want to view
a zml file through the ZMLCreator, just select open through the file menu. The
already existing functions will be available under
path-to-sicraft
/toolboxes/.
Under the starting screen (Functionnode), there are several values you can set:
- Title: This will be the name of the Function, which will be displayed in
the GUI.
- Filename: This shall be the path to the file were the function you want to
run is situated. The active directory will be set to the file the zml file
resides in, so if the other file is in the same directory, just writing its
name will be sufficient.
- Plugin: The exact name of the plugin you want to run, currently OctavePlugin,
RPlugin and PythonPlugin. All available plugings will reside int he directory
Library/Plugins. Even though a combobox is used for selection, you may write whatever
you want here.
- Description: The text which will show up under the description field when
you open a node dialog.
- Menu Pos.: Normally, a node's position in the node-tree will be decided by
the directory it's in. If this value is set however, it will be placed there
instead. To indicate several directories, please use `,' as a seperator (this
may be changed later).
- Documentation path: Path to documentation concerning this functionnode.
To add an Inputport please select add inputport under the edit menu. Values that may be set are:
- Name: The name of the inputport as well as the name under which the data will be made available to the function.
- Description: Whatever you write here, will show up on under the
description fields in SciCraft.
- Named: Determines whether the port name should be send as a named argument to the target function.
To add an Outputport please select add outputport under the edit menu. Values that may be set are:
- Name: The name of the outputport as well as the variablename SciCraft will check for data.
- Description: Whatever you write here, will show up on under the
description fields in SciCraft.
- Subobject: Associate a part of the output from a R function with this port, e.g. the string out$version
will extract the attribute version from the return value out. (Only available when plugin type for the functionnode is set to RPlugin).
To add a Parameter please select add parameter under the edit menu.
All parameters may have restrictions placed upon them. The values you can set
means the following:
- Name: The name of the parameter as well as the name under which the data will be made available to the function.
- Description: Whatever you write here, will show up on under the
description fields in SciCraft.
- Type: The valid types are: Integer, Float, Text, Fileopen, Filesave. There
are no maximum limit for Integer(or rather Long objects which large values
will be stored as) or Text objects. Python uses double-precision Floats. If
type is Fileopen or Filesave, the user will be prompted with a Filedialog in
the GUI, and the parametervalue will be set to the path.
- Min/Max: For integers and floats, these will be restrict the values the user
may set the parameter to. Please use `.' and not `,' as seperator.
- Min/Max: For strings, these will be the max/min number of chars the value
can have.
- Step: If set for integers and floats, a step value may be set.
- Default: Available for all types; this value will simply be the default
value which is showned when no value has been set yet.
- Restrictions: If set, this options will override all other
restrictions and the user will be prompted with a ComboBox in which he may select
one of the values from this list.
The following example shows a function that will use a PCA script with two input and three
output ports:
<function>
<title>pca</title>
<filename>pca.m</filename>
<description>This function performs a Principal Components Analysis</description>
<plugin>OctavePlugin</plugin>
<input>
<port>
<name>X</name>
<type></type>
<description>Input data matrix</description>
</port>
<port>
<name>aMax</name>
<type></type>
<description>Number of components</description>
</port>
</input>
<output>
<port>
<name>t</name>
<type></type>
<description>Scores</description>
</port>
<port>
<name>P</name>
<type></type>
<description>Loadings</description>
</port>
<port>
<name>E</name>
<type></type>
<description>Residuals</description>
</port>
</output>
</function>
SciCraft Development Team