Diff for "Cytoscape_2.8/EquationAttributes"

Proposal

Add the ability to Cytoscape to describe attributes as being derived or computed based on expression which may involve references to other attributes.

Background

This capability would seem to be a natural extension in the attribute browser. Especially for numerical-valued attributes it seems obvious that Cytoscape users might want to derive new quantities based on the values of other attributes. A similar argument holds for boolean attributes.

Use Cases

• Allows users to easily colour a node based on a threshold value. Example: Given a Double attribute "someValue" and a threshold called "someThreshold" we could create a new boolean attribute called "exceedsThreshold" which would be defined by an equation attribute that is "$(someValue) > someThreshold".

• Assume we have an attribute called "someAttrib" and we would like to assign colour values based on the log of this attribute's value then we could assign a new new Double attribute "shiftedLog" defined by "log10($(someAttrib)) + 22.7"
• Consider an attribute that has missing values called "maybeMissing" and assume we could like to provide a derived attribute that has a default value of -10.2 when ever "maybeMissing" is not set, then we could create a new attribute called "neverMissing" defined by "$(maybeMissing=-10.2)"

Many more complex examples can be easily construed.

Implementation Plan

1. Define a syntax for the expressions (Cull this as a subset from some programming language's grammar?)

2. Write a parser (LL(1) grammar, recursive descent (http://en.wikipedia.org/wiki/Recursive_descent_parser)) implementing the syntax and error handling (Pay special attention to easy extension with more built-in functions.)

3. Test and debug the stand-alone parser
4. Identify the location in the Cytoscape code base for integration and integrate the parser
5. Test and debug the new capability within Cytoscape

Project Timeline

1. Define syntax (est. 1/2 day to 1 day)
2. Implement and test stand-alone parser (3 to 4 days)
3. Integrate the parser into the Cytoscape code base (3 to 4 days)

Total time: 6 1/2 to 9 days.

Tasks and Milestones

1. Define syntax
   1. Cull a subset of the "C" syntax that corresponds to what we want to implement
   2. Check for violations of LL(1) and transform to LL(1), if necessary
2. Implement and test stand-alone parser

   1. Write a scanner/tokenizer (GetToken/UngetToken)

   2. Convert the syntax into a series of recursive function calls
   3. Add type checking and error handling
   4. Create unit tests
   5. Implement the built-in functions (Possibly add the capability to register Java function objects as built-in functions.)
   6. Test and debug
3. Integrate the parser into the Cytoscape code base
   1. Find where in the Cytoscape code base would be the natural location for integration
   2. Actually integrate the new code
   3. Create unit tests for the integrated code
   4. Test the new code as part of Cytoscape
   5. Manually test and debug the new code and possibly extend the unit tests

Project Dependencies

This project does not depend on any other projects.

Informal Description of Equation Syntax and Functions

Attribute References

References to existing, possibly empty attributes can take two forms:

1. Unconditional references look like $(attribName). This type of reference results in an error should the attribute "attribName" not exist or if it exists but has no assigned value.

2. Conditional references look like $(attribName=defaultValue). This type of reference results in an error should the attribute "attribName" not exist or if the type of "defaultValue" is inconsistent with the type of "attribName". If attribName exists but is empty, the default value "defaultValue" will be substituted instead.

Initially only references to Double, Int, String and Boolean attributes will be allowed. In the case of Boolean attribute references the two predefined constants true and false will be the only possible default values.

Expressions

In addition to String, Integer, Double and List attributes, it is also possible to define "attributes" that are functions of one or more other attributes. These functions may be string-, integer-, double-, or list-valued and refer to other attributes. In the case of Integer and Double attributes, you may used arbitrary arithmetic expression using addition, subtraction, multiplication, exponentiation (using "^"), as well as a small set of predefined mathematical functions and grouping and nesting using parentheses. Currently the supported functions are:

Built-In Functions

Operators

The usual complement of arithmetic as well as boolean comparison operators will be provided. Operator precedence will probably follow the C/Java/FORTRAN conventions.

|| "-" || subtraction || Double/Int, Double/Int || Double || may result in -Inf or +Inf

String Constants a.k.a. String Literals

String literals are sequences of characters enclosed in double-quotes. Double-quotes, newlines or backslashes may be embedded in a string literal by preceding them with a backslash.

Error Reporting

Type errors or arithmetic errors are reported in the field that contains the equation, for example if the function attempts to add a string and an integer or if an equation references a non-existent or empty attribute without providing a default. (Note: This may need some more thought, for example we may consider to provide an empty value in case of an error.)

Comments

• Add comment here…

How to Comment

Edit the page and add your comments under the provided header. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment. Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the RFC makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.