= 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_developer_tutorial#How_to_add_new_attribute_functions_via_a_Cytoscape_plug-in|plugin tutorial for the creation of a Cytoscape plugin that adds attribute functions to Cytoscape dynamically]].