Implementing_Attribute_Equations_Functions - Cyt... http://cytoscape.wodaklab.org/wiki/Implementing_...

Implementing Attribute Equations
Functions
You need the equations.jar file for this which comes with Cytoscape 2.8 and later. But, it
is will be extremely helpful to study the source code for the built-in functions that are in
the "equations" core Cytoscape library under src/org/cytoscape/equations/builtins. In
fact, in many cases you may want to implement a function with a signature (= argument
list) identical to that of an existing function, in which case you should probably start with
a copy of an existing function with the same argument list.

Should you choose to or are required to implement a new function entirely from scratch,
you can derive a class either from org.cytoscape.equations.Function or
org.cytoscape.equations.AbstractFunction. While you gain some additional flexibility in
the choice of arguments that your function may have by deriving your class directly from
the Function class, this is not recommended and we suggest to derive your function from
the AbstractFunction class instead. Deriving from AbstractFunction will greatly reduce
the complexity of your task and save you the work of implementing
Function.getUsageDescription(), Function.argTypesAreValid(), and
Function.getPossibleArgTypes(). From now on we will assume that you intend to
follow this route!

The first step is implementing the constructor for your function. Here is the constructor
for the Substitute built-in function:

public Substitute() {
        super(new ArgDescriptor[] {
                        new ArgDescriptor(ArgType.STRING, "text", 
"The source text."),
                        new ArgDescriptor(ArgType.STRING, 
"original", "The text that will be replaced."),
                        new ArgDescriptor(ArgType.STRING, 
"replacement", "The replacement text."),
                        new ArgDescriptor(ArgType.OPT_INT, 
"nth_appearance", "Which occurrence to replace.")
                });
}

This constructor should take no arguments and include a call to super where you need to
specify the arguments that your function will take. The single argument in the call to

1 di 3 16/12/2010 15:35
Implementing_Attribute_Equations_Functions - Cyt... http://cytoscape.wodaklab.org/wiki/Implementing_...

super is an array of type org.cytoscape.equations.ArgDescriptor and it will usually
be an array literal. Each ArgDescriptor constructor takes 3 parameters. The first is the
type of argument and is an enum value of type org.cytoscape.equations.ArgType, the
2nd one is the name of the argument as it will appear in the browser's formula builder
and the last argument is a short description of what the argument is or what its
requirements or limitations are.

The ArgType is the hardest and most important to understand. While there is hopefully
decent documentation of each value in org.cytoscape.equations.ArgType, it is helpful to
understand the following rules:

* ArgTypes starting with OPT_ are optional and may only appear at the end of the
argument list. (There may be zero or more trailing optional arguments.)

* ArgTypes starting with or containing STRICT_ imply that the type provided by a
caller must be exactly of this type. Should the STRICT_ be missing a valiant effort will
be made to convert to this type, e.g. strings like "2.3" will be converted to a floating
point number, TRUE can be converted to 1 or 1.0 and FALSE to 0 or 0.0 etc.

* Plurals like INTS and BOOLS imply that one or more lists and/or scalars may be
provided in an actual call. For example a function having been declared to take FLOATS
may take a list of floating points followed by two individual numbers and all these
separate arguments will be matched by this. One consequence of that is that you can't
have FLOAT following FLOATS, but you could have STRICT_FLOATS followed by
float because this would imply a single list of floats followed by a single scalar that will
be converted to a float etc.

The getName(), getFunctionSummary(), and getReturnType() methods are probably
selfexplanatory. The evaluateFunction() method will depend on both, your defined
argument list, as well as the intended functionality of your function. Our advice here is
the use of utility methods from the org.cytoscape.equations.FunctionUtil class that
can greatly assist in the argument processing. For example the
FunctionUtil.getArgAsDouble() method will try to convert passed booleans, strings
and integers to type double etc. One important pitfall to be aware of is that attribute
equations process integers internally as type Long and not Int!

It is clear to us that the information contained here is not sufficient to implement your
own functions. The best place to start is probably by reading the implementations of
some existing functions and studying the plugin tutorial for the creation of a Cytoscape
plugin that adds attribute functions to Cytoscape dynamically.

2 di 3 16/12/2010 15:35
Implementing_Attribute_Equations_Functions - Cyt... http://cytoscape.wodaklab.org/wiki/Implementing_...

Implementing_Attribute_Equations_Functions (last edited 2010-07-08 20:21:42 by JohannesRuscheinski)

3 di 3 16/12/2010 15:35