Attribute Formulas

Introduction

As of Cytoscape 2.8, attribute values may be formulas. A typical example is =ABS($otherAttrib + LOG(10.2)). Formulas are modelled after Excel™ but only support references to other attributes at the same node, edge or network. Since Cytoscape attribute names may contain embedded spaces, optional braces around the attribute name (required if the name is not simply a letter followed by one or more letters or digits) is allowed e.g. ${a name with spaces}. Backslashes, opening braces and dollar signs in attribute names have to be escaped with a leading backslash. For example the attribute name ex$am{p\le would have to be written as ${ex\$am\{p\\le}. ID is being treated as a pseudo-attribute. String constants are written with double-quotes ". In order to embed a double-quote or a backslash in a string they have to be escaped with a leading backslash, therefore the string "\ must be written as "\"\\". Formula results must be compatible with the type of the attribute that they have been assigned to. The rules are rather lax though, for example anything can be interpreted as a string and all numeric values will be accepted for a boolean (or logical) attribute where non-zero will be interpreted as true and zero as false. For integer attributes floating point values will be converted using the rules of the Excel™ INT function. Parentheses can be used for grouping and to change evaluation order. The operator precedence rules follow those of standard arithmetic.

Operators

Currently supported operators are the four basic arithmetic operators and the ^ exponentiation operator. +, -, *, and \ are left-associative and ^ is right-associative. The string concatenation operator is &. Supported boolean or logical operators are the comparison operators <, >, <=, >=, =, and <> (not equal).

Supported Functions

Currently we support the following functions:

Cytoscape-specific functions

Numeric Functions

String Functions

Logical/Boolean Functions

List Functions

Statistical Functions

Miscellaneous Functions

Pitfalls

The possibly biggest problem is the referencing of other attributes that have null values. This is not allowed and leads to errors. In order to mitigate this problem we support the following optional syntax for attribute references: ${attribName:defaultValue}. The interpretation is that if attribName is null, then the default value will be used, otherwise the value of the referenced value will be used instead. N.B., the referenced attribute must still be a defined attribute and not an arbitrary name! The other potential problem is when there are circular attribute reference dependencies. Circular dependencies will be detected at formula evaluation time and lead to a runtime error.

Useful Tips

When working with formulas it can be very helpful to open the Cytoscape Error Console. Formula evaluation errors will be logged there.

The Formula Builder

In order to ease the creation of formulas as well as to facilitate discovery of built-in functions we provide a formula builder in our attribute browser. After selecting a non-list attribute cell, you can invoke it by clicking on fx-button.png. This should bring up the Formula Builder which looks like this:

formula-builder.png

The Formula Builder is a useful tool for discovery of the list of built-in functions. Arguments can either be selected from a list of named attributes or constant values can be entered in a text entry field. A major shortcoming at this time is that the Formula Builder won't let you compose functions with function calls as arguments. If you need the most general functionality, please type the expression directly into a cell.

A Note for Plugin Writers

It is relatively easy to add your own built-in formula functions. A simple function can probably be implemented in 15 to 20 minutes. It can then be registered via the parser and becomes immediately available to the user. It will of course also show up in the drop-down list in the formula builder.

Cytoscape_User_Manual/Attribute_Formulas (last edited 2010-09-27 20:28:17 by malbec)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux