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