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

• Degree -- the degree of a node.

• InDegree -- the indegree of a node.

• OutDegree -- the outdegree of a node.

• SourceID -- the ID of the source node of an edge.
• TargetID -- the ID of the target of an edge.

Numeric Functions

• Abs -- Returns the absolute value of a number.
• ACos -- Returns the arccosine of a number.
• ASin -- Returns the arcsine of a number.
• ATan2 -- Returns the arctangent of two numbers x and y.
• Average -- Returns the average of a group of numbers.
• Cos -- Returns the cosine of an angle given in radians.
• Cosh -- Returns the hyperbolic sine of its argument.
• Count -- Returns the number of numeric values in a list.
• Degrees -- Returns its argument converted from radians to degrees.
• 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 an approximation of the value of π.
• Radians -- Returns its argument converted from degrees to radians.
• Round -- Rounds a number to a specified number of decimal places.
• Sinh -- Returns the hyperbolic sign of its argument.
• Sin -- Returns the sine of an angle given in radians.
• Sqrt -- Calculates the square root of a number.
• Tan -- returns the tangent of its argument in radians.
• Trunc -- Truncates a number.

String Functions

• Concatenate -- Concatenates two or more pieces of text.
• Left -- Returns a prefix of s string.
• Len -- Returns the length of a string.
• Lower -- Converts a string to lowercase.
• Mid -- Selects a substring of some text.
• Right -- Returns a suffix of a string.
• Substitute -- Replaces some text with other text.

• Text -- Format a number using the Java DecimalFormat class' conventions.

• Upper -- 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

• BList -- creates a list of boolean (a.k.a. logical or truth) values
• First -- Returns the first entry in a list.
• FList -- creates a list of floating point (a.k.a. decimal) numbers
• Last -- Returns the last entry in a list.
• IList -- creates a list of integers (a.k.a. whole numbers)
• Nth -- Returns the n-th entry in a list.
• SList -- creates a list of strings (a.k.a. text objects)

Statistical Functions

• Largest -- the kth largest value in a list.

• GeoMean -- the geometric mean of a set of numbers.

• HarMean -- the harmonic mean of a set of numbers.

• Mode -- the mode of a set of numbers.

• NormDist -- Returns the pdf or CDF of the normal distribution.

• Permut -- Returns the number of permutations for a given number of objects.

• StDev - sample standard deviation.

• Var -- sample variance.

Miscellaneous Functions

• Combin - Returns the number of combinations for a given number of objects.
• If -- Returns one of two alternatives based on a boolean value.

• ListToString -- Returns a string representation of a list.

• Now -- Returns a string representation of the current date and time.
• Today -- returns a string representation of the current date.

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 . This should bring up the Formula Builder which looks like this:

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

Enhanced Search

Cytoscape includes a search feature, which enables you to quickly find nodes and edges.

Using Search is very simple. For example, type in "YL*" in the search box will find all the nodes/edges with string "YL" as prefix in the attributes. Type in "name:YL*" will restrict the search to attribute 'name' only. You can also use 'and', 'or' to make the complex search. The searching is actually based on Apache Lucene. Please look at this page for more about search syntax.

Filters

Filters allow you to quickly select multiple nodes or edges of interest by comparing node and edge attributes to properties you specify. For example, you can select all the nodes whose name contains a specific pattern, or whose numeric attribute value falls within a certain range. You can also perform complex selection by defining filters and performing the Boolean operation between them.

Using Filters

By default, you should see a filter icon on the toolbar: . If you click on it, the filters tab on the Control Panel will be selected. You can also access the filters by clicking directly on the tab or by using the Select menu pull-down and choose “Use Filters” menu item. The filters panel initially looks like this:

1. Filter Definition

To create a new filter, click the option button and select “Create new filter” from the list provided. Enter a name for the new filter.

Definition of simple filter

When a new filter is created, it is empty initially. It can be defined by choosing attributes (one at a time) in the Attribute/Filter comboBox and clicking the Add button. Note that in the comboBox each attribute has a prefix, either node. or edge., denoting what type of attribute it is. After add button is clicked, a widget, depended on the item selected, will be added to the definition panel. If the attribute type is text-based (or String), the widget will be a indexed-text-box widget, if numeric attribute, the widget will be a range slider; both are shown below.

For each widget, the name of the attribute it represents is on the left. A NOT checkbox gives the option to get the negation of selection for the widget. There is a trash-can icon on the right. Clicking on the trash-can icon will delete the widget. In this way, the filter definition can be modified after it is defined.

Note that if more than one widget is added on the filter definition panel, the relationship between them is “AND” by default. This relationship can be changed to “OR” by selecting the OR relation in Advanced Panel.

The Advanced panel can be opened by clicking on the plus (+) sign.

There are three rows in the advanced panel:

1. The first row, labeled Save. The two checkboxes (Global and Session) will determine where the filter is saved. By default, filters are saved in individual sessions. If the Global checkbox is checked, the filter will be saved in the global properties file. Note also that the prefix of the filter name in the Current Filter dropdown list reflects where it is saved.

2. The second row, Relation, will determine what Boolean operation (AND or OR) will be applied to each individual widget.

3. Negation checkbox. If this checkbox is checked, the result of the filter will be negated.

Definition of complex filter

In the pull-down list of Attribute/Filter comboBox, there are two sections, the top one is the list of attributes, the bottom one is the list of previously defined filter. Those previously dfined filters can also be used as components of other filters. By combinational use of AND, OR, NOT and pre-defined filters, filters with arbitary complexity can be defined.

3. Apply the filter

If a network is small (number of nodes or edges less than 1000), the filter will be applied dynamically when a widget is added or any value is adjusted. If the network is large, then Apply button should be clicked to apply the filter.

The threshold (1000 by default) can be changed by defining a Cytoscape property value dynamicFilterThreshold.

4. Other filters

In the option menu pulldown, there are menu items “Create new topology filter”, “Create new NodeInteraction filter” and “Create new EdgeInteraction filter”.

Topology Filter

Topology filter will select nodes based on the properties of its near-by nodes (neighbors). To create a topology filter, choose the menu item “Create new topology filter” from the option menu. See below,

Interaction filter

Interaction filters are used to select nodes/edges based on the properties of their neighboring edges/nodes. See below for a node interaction filter.

The Select Menu

The Select → Nodes and Select → Edges menus provide several mechanisms for selecting nodes and edges. Most options are fairly straightforward; however, some need extra explanation.

Select → Nodes → From ID List File... selects nodes based on node identifiers found in a specified file. The file format is simply one node id per line:

Node1
Node2
Node3
...

Using Cytoscape you can edit networks and add nodes and edges. In Cytoscape 3.x editing can be done using right click menus on the network view panel. To start editing a new network, create a new network by going to File → New → Network → Empty Network.

Adding Node

To add a new node right click on an empty space of the network view panel. Select Add → Add Node item from the poped up menu. Image below shows the right click menu for creating a new node.

Adding Edge

For adding an edge to connect to nodes, you need to right click on the source node. Select Add Edge from the popped up menu. Next, click on the target node. Images below show the two steps for drawing an edge between two nodes. You can abort the drawing of the edge by clicking on an empty spot on the palette.

You can delete nodes and edges by selecting a number of nodes and edges, then selecting Edit → Delete Selected Nodes and Edges. You can recover any nodes and edges deleted from a network by going to Edit → Undo.

LinkOut provides a mechanism to link nodes and edges to external web resources within Cytoscape. Right-clicking on a node or edge in Cytoscape view opens a popup menu with a list of web links.

The external links are specified in a linkout.props file which is included in the cytoscape.jar file. The defaults include a number of links such as Entrez, SGD, iHOP, and Google, as well as a number of species-specific links. In addition to the default links, users can customize the LinkOut menu and add (or remove) links by editing the linkout properties (found under Edit → Preferences → Properties...).

External links are listed as ‘key’-‘value’ pairs in the linkout.props file where key specifies the name of the link and value is the search URL. The LinkOut menus are organized in a hierarchical structure that is specified in the key. Linkout key terms specific for nodes start with the keyword nodelinkouturl, for edges this is edgelinkouturl.

For example, the following entry:

nodelinkouturl.Model Organism DB.SGD (yeast)=http://db.yeastgenome.org/cgi-bin/locus.pl?locus=%ID%

places the SGD link under the Model Organism DB submenu. This link will appear in Cytoscape as:

In a similar fashion one can added new submenus.

The %ID% string in the URL is a place-holder for the node label. When the popup menu is generated this marker is substituted with the node label. In the above example, the generated SGD link for the YPL211W protein is:

http://www.yeastgenome.org/cgi-bin/locus.fpl?locus=YPL211W

If you want to query based on a different attribute you currently need to specify a different Node Label using the VizMapper.

For edges the mechanism is much the same; however here the placeholders %ID1% and %ID2% reflect the source and target node label respectively.

Currently there is no mechanism to check whether the constructed URL query is correct and if the node label is meaningful. Similarly, there is no ID mapping between various identifiers. For example, a link to NCBI Entrez from a network that uses ensembl gene identifiers as node labels will produce a link to Entrez using ensembl ID, which results in an incorrect link. It is the user's responsibility to ensure that the node label that is used as the search term in the URL link will result in a meaningful link.

Adding or Removing Links

The default links are defined in a linkout.props file contained in linkout.jar. These links are normal java properties and can be edited by going to Edit → Preferences → Properties... . New links can be defined this way as well. New links can be defined at startup in a separate file and loaded from the command line, either by specifying a file containing the links

cytoscape.sh -P new_linout.props

or as individual properties

cytoscape.sh -P nodelinkouturl.yeast.SGD=http://db.yeastgenome.org/cgi-bin/locus.pl?locus\=%ID%

Any links defined on the command line will supersede the default links.

To remove a link from the menu simply delete the property, using Edit → Preferences → Properties... .

Use LinkOut from Attribute Browser

From Cytoscape 2.6.0, you can use LinkOut from Attribute Browser. Basic functionality is the same, and the only difference is the parameter passed to the LinkOut is value in the selected cell.