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}. 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 rules for this 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:

Numeric Functions

• Abs -- Returns the absolute value of a number.
• Average -- Returns the average of a group of numbers.
• Count -- Returns the number of numeric values in a list.
• Exp -- Returns e raised to a specified number.
• Ln -- Returns the natural logarithm of a number.
• Log -- Returns the logarithm of a number to a specified base.
• Max -- Returns the maximum of a group of numbers.
• Median -- Returns the median of a list of numbers.
• Min -- Returns the minimum of a group of numbers.
• Mod -- Calculates the modulus of a number.
• Pi -- Returns the value of π.
• Round -- Rounds a number to a specified number of decimal places.
• Sqrt -- Calculates the square root of a number.
• Trunc -- Truncates a number.

String Functions

• LCase -- Converts a string to lowercase.
• Left -- Returns a prefix of s string.
• Len -- Returns the length of a string.
• Mid -- Selects a substring of some text.
• Right -- Returns a suffix of a string.
• Substitute -- Replaces some text with other text.
• UCase -- Converts a string to uppercase.
• Value -- Converts a string to a number.

Logical/Boolean Functions

• And -- Returns the logical conjunction of any number of boolean values.
• Not -- Returns the logical negation of a boolean value.
• Or -- Returns the logical disjunction of any number of boolean values.

List Functions

• First -- Returns the first entry in a list.
• Last -- Returns the last entry in a list.
• Nth -- Returns the n-th entry in a list.

Miscellaneous Functions

• If -- Returns one of two alternatives based on a boolean value.

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.

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.