Help - Old:Calculating node/branch data (until 2.12.0)

From TreeGraph help
Jump to: navigation, search
ArticleOnOlderVersion.png This article describes this feature for TreeGraph 2.12.0 or (not necessaryly all) earlier versions. See here for the article on the latest version and a list on other available article versions.


The Calculate node/branch data... function allows you to specify an mathematical expression which defines values for all lines of a node/branch data column. In this expression you can reference the current values of the specified column as well as the values of all other columns. Additionally a set of predefined functions and constants (see below) can be used.

Note that this feature was not available before version 2.0.24. The Edit node/branch data-dialog which was present before this version offered a set of rescaling operations instead. It is recommended to use the latest version of TreeGraph 2.

The dialog

The "Calculate node/branch data"-dialog

To access the Calculate node/branch data-dialog select EditNode/branch dataCalculate node/branch data... from the main menu.

Column

Here you can select the node/branch data column that shall be calculated. The column which was selected in the document window is preselected here if it is editable.

Expression

You can type in a mathematical expression like it is describes below here.

Recently used expressions

In this list you select one of the last 25 valid expressions you have specified to use them again.

Expressions

Accessing single values of node/branch data columns

TreeGraph 2 offers two functions to directly access other node/branch data values:

  • getValue: Returns the value of a node/branch data column in the same line as the cell that is currently calculated.
  • getParentValue: Returns a value in the specified column attached to the parent node of the current node (associated with the line that is currently calculated).

Both functions can take one or two parameters. The first parameter always specifies the column that should be referenced either by its ID (if it is a hidden node/branch data or a label column) or by a special key word (see below) used to identify the default node name-, node name- or branch length-column.

The second parameter is optional and defines a default value which is returned if the referenced column does not contain a value in the current line. If no default value is specified and the referenced column contains no value the calculation for this line is aborted and the value stored in the target column will be empty.

Examples

Expression: Description:
getValue(NAME) Returns the node name in the current line. (Could be a numeric or a textual value.)
getValue(LENGTH) Returns the branch length in the current line.
getValue(LENGTH, 0) Returns the branch length in the current line or 0 if no branch length is specified.
getValue("id1") Returns the value of the column with the ID "id1" in the current line. (This could be a hidden node data-, a hidden branch data or a label column.)
getParentValue(THIS, 0) + 1 Adds one to the value in the same column attached to the parent node.
getParentValue("brLensSum", 0) + getValue(LENGTH) This expression calculates the overall branch length from the root to the current node saved on a column with the ID "brLensSum".

Checking node/branch data

The functions following two functions can be used to check whether a node/branch data column contains a value in the current line or its parent.

  • hasValue
  • hasParentValue

It has one parameter which specifies the column (analog to getValue) that shall be checked. This function can be helpful in combination with the if-function (see below) in an expression like this:

if(hasValue("id1") || hasValue("id2"), getValue(NAME), "undefined")

Note that the functions getParentValue and hasParentValue were not available before version 2.4.0.

Special keywords

The following special keywords can be used with the getValue or hasValue functions.

  • THIS: References the column which shall be calculated by this expression. (E.g. getValue(THIS) * 2 would set the new value of this column as two times the old value.)
  • UNIQUE: References the unique node name column.
  • NAME: References the node name column.
  • LENGTH: References the branch length column.

Operators

The following list contains all valid operators. Each operator binds as strong or more than all operators listed below. The right columns indicate of which types the operands have to be.

Name: Operator: Numeric: Textual: Boolean: Example:
Power ^ YesSymbol.png NoSymbol.png NoSymbol.png 10^-2 (= 0.02)
Unary plus + YesSymbol.png NoSymbol.png NoSymbol.png +4
Unary minus - YesSymbol.png NoSymbol.png NoSymbol.png -4
Modulo % YesSymbol.png NoSymbol.png NoSymbol.png 10 % 4 (= 2)
Division / YesSymbol.png NoSymbol.png NoSymbol.png getValue(LENGTH) / 2
Multiplication * YesSymbol.png NoSymbol.png NoSymbol.png getValue("id1") * 100
Addition + YesSymbol.png YesSymbol.png NoSymbol.png
getValue("id1") + 10
"Two " + "words"
Less or equal <= YesSymbol.png NoSymbol.png NoSymbol.png if(getValue(THIS) <= 100, getValue(THIS), 100)
Greater or equal >= YesSymbol.png NoSymbol.png NoSymbol.png if(getValue(THIS) <= 100, "A", "B")
Less then < YesSymbol.png NoSymbol.png NoSymbol.png if(getValue(THIS) < 100, getValue(THIS), 100)
Greater then > YesSymbol.png NoSymbol.png NoSymbol.png if(getValue(THIS) < 100, "A", "B")
Equal = YesSymbol.png YesSymbol.png NoSymbol.png if(getValue(THIS) = 100, getValue("id"), getValue("id2"))
Not equal != YesSymbol.png YesSymbol.png NoSymbol.png if(getValue(THIS) != "empty", getValue("id1"), 0)
And && NoSymbol.png NoSymbol.png YesSymbol.png if(getValue(THIS) < 100 && getValue(THIS) > 50, getValue("id1"), "")
Or || NoSymbol.png NoSymbol.png YesSymbol.png if(hasValue("id1") || hasValue("id2"), getValue(NAME), "undefined")

Mathematical functions referencing other cells

Each of these functions calculates a value from a set of other values and has three forms:

  • Standard form: Takes a list of any numeric values and calculates the result from these. (Example: sum(10, 5, getValue("colA"), 12)).
  • Line form: Uses all line (values from all nodes) of one node/branch data column to calculate the result. (Example: sumOfLines("colA") return the sum of all values in colA.)
    • If any line of that column does not contain a numeric value, it is ignored.
  • Column form: Uses the values of different columns attached to the currently calculated node to determine the result. It takes a list of column IDs as parameters. (Example: sumOfColumns("colA", "colB", "colC") returns the sum of the values in the three specified columns in the current line.)
    • If any of the specified columns contains no numeric value, it is ignored in the calculation. (That is the advantage of using the column form instead of sum(getValue("colA"), getValue("colB"), getValue("colC")), which would fail if any of the three columns contains no or a non-numeric value.)


Name: Definition: Description:
Sum sum(Numeric v1, Numeric v2, ...) Returns the sum of all passed parameters. Two or more parameters can be passed.
sumOfLines(ColumnReference r1) Returns the sum of all lines of the specified node/branch data column. Exactly one column reference (column ID or special keyword) must be passed.
sumOfColumns(ColumnReference r1, ColumnReference r2, ...) Returns the sum of the values of all specified node/branch data columns attached to the currently calculated node. One ore more column references (column ID or special keyword) can be passed.
Product product(Numeric v1, Numeric v2, ...) Returns the product of all passed parameters. Two or more parameters can be passed.
productOfLines(ColumnReference r1) Returns the product of all lines of the specified node/branch data column. Exactly one column reference (column ID or special keyword) must be passed.
productOfColumns(ColumnReference r1, ColumnReference r2, ...) Returns the product of the values of all specified node/branch data columns attached to the currently calculated node. One ore more column references (column ID or special keyword) can be passed.
Maximum value max(Numeric v1, Numeric v2, ...) Returns the maximum of all passed parameters. Two or more parameters can be passed.
maxOfLines(ColumnReference r1) Returns the maximum of all lines of the specified node/branch data column. Exactly one column reference (column ID or special keyword) must be passed.
maxOfColumns(ColumnReference r1, ColumnReference r2, ...) Returns the maximum of the values of all specified node/branch data columns attached to the currently calculated node. One ore more column references (column ID or special keyword) can be passed.
Minimum value min(Numeric v1, Numeric v2, ...) Returns the minimum of all passed parameters. Two or more parameters can be passed.
minOfLines(ColumnReference r1) Returns the minimum of all lines of the specified node/branch data column. Exactly one column reference (column ID or special keyword) must be passed.
minOfColumns(ColumnReference r1, ColumnReference r2, ...) Returns the minimum of the values of all specified node/branch data columns attached to the currently calculated node. One ore more column references (column ID or special keyword) can be passed.
Mean value mean(Numeric v1, Numeric v2, ...) Returns the mean of all passed parameters. Two or more parameters can be passed.
meanOfLines(ColumnReference r1) Returns the mean of all lines of the specified node/branch data column. Exactly one column reference (column ID or special keyword) must be passed.
meanOfColumns(ColumnReference r1, ColumnReference r2, ...) Returns the mean of the values of all specified node/branch data columns attached to the currently calculated node. One ore more column references (column ID or special keyword) can be passed.

Note that none of these functions was available before version 2.0.47. mean and all line and column forms were not available before version 2.4.0.

Functions related to the topological position

The following boolean functions can be used to check topological properties of the current node. They can be combined with the if function e.g. to use different expressions for terminal or internal nodes or the root.

  • isLeaf(): Returns 1 if the current node is a terminal node or 0 otherwise.
  • isRoot(): Returns 1 if the current node is the root of the tree or 0 otherwise.
  • indexInParent(): Returns the index the current node has in its parent. Note that the first node has the index 0 (not 1). If this function is called on the root node, it will return -1.

Note that none of these functions was available before version 2.4.0.

General mathematical functions

Name: Definition: Description:
Sine sin(Numeric x) Calculates the sine of the passed numeric value.
Cosine cos(Numeric x) Calculates the cosine of the passed numeric value.
Tangent tan(Numeric x) Calculates the tangent of the passed numeric value.
Inverse sine asin(Numeric x) Calculates the inverse sine of the passed numeric value.
Inverse cosine acos(Numeric x) Calculates the inverse cosine of the passed numeric value.
Inverse tangent atan(Numeric x) Calculates the inverse tangent of the passed numeric value.
Inverse tangent atan2(Numeric x, Numeric y) Calculates the inverse tangent (or arcus tangent) of y / x given adjacent and x. The result is between -π and π
Hyperbolic sine sinh(Numeric x) Calculates the hyperbolic sine of the given angle.
Hyperbolic cosine cosh(Numeric x) Calculates the hyperbolic cosine of the given angle.
Hyperbolic tangent tanh(Numeric x) Calculates the hyperbolic tangent of the given angle.
Inverse hyperbolic sine asinh(Numeric x) Calculates the inverse hyperbolic sine of the given angle.
Inverse hyperbolic cosine acosh(Numeric x) Calculates the inverse hyperbolic cosine of the given angle.
Inverse hyperbolic tangent atanh(Numeric x) Calculates the inverse hyperbolic tangent of the given angle.
Natural logarithm ln(Numeric x) Calculates the natural logarithm of the passed numeric value.
Logarithm to the base 10 log(Numeric x) Calculates the logarithm to the base 10 of the passed numeric value.
Exponential function exp(Numeric x) Calculates the exponential function to the base e. It is the inverse function of the natural logarithm (ln).
Magnitude abs(Numeric x) Returns the absolute value of the passed numeric parameter.
Random number rand(Numeric x) Returns a random number between 0 and 1.
Square Root sqrt(Numeric x) Calculates the square root of the passed numeric parameter.
Alternative if(Boolean condition, Numeric or textual trueValue, Numeric or textual falseValue) Returns the second parameter if the condition is true or the third if not.
Number to text str(Numeric or textual x) Returns a textual representation of the passed parameter.

Constants

  • Euler's number: e
  • π: pi

See also