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.

R

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))
}

Python

When importing a Python function into SciCraft there are a few things to keep in mind.
  1. The function node you create needs both an input and an output port.
  2. The input port(s) that you create has to have the same name(s) as the parameters in your python function.
  3. All import statements have to be done inside the python functions.
  4. 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>Integer</type>
            <description>Math.sin calculation</description>
        </port>
        <port>
            <name>input2</name>
            <type>Integer</type>
            <description>Multiplier</description>
        </port>
    </input>
    <output>
        <port>
            <name>result1</name>
            <type>Float</type>
            <description>Partial result, multiplier</description>
        </port>
        <port>
            <name>result2</name>
            <type>Float</type>
            <description>Final result</description>
        </port>
     </output>
</function>


Importing functions into SciCraft

Creating ZML files

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.18). 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.18: The ZMLCreator.

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/.

Functionnode settings

Under the starting screen (Functionnode), there are several values you can set:

Inputport settings

To add an Inputport please select add inputport under the edit menu. Values that may be set are:

Outputport settings

To add an Outputport please select add outputport under the edit menu. Values that may be set are:

Parameter settings

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:

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>Text</type>
            <description>Input data matrix</description>
        </port>
        <port>
            <name>aMax</name>
            <type>Integer</type>
            <description>Number of components</description>
        </port>
    </input>
    <output>
        <port>
            <name>t</name>
            <type>Integer</type>
            <description>Scores</description>
        </port>
        <port>
            <name>P</name>
            <type>Integer</type>
            <description>Loadings</description>
        </port>
        <port>
            <name>E</name>
            <type>Float</type>
            <description>Residuals</description>
        </port>
     </output>
</function>


SciCraft Development Team