Help - Old:Calculating node/branch data (until 2.12.0)
|
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.
Contents
The dialog
To access the Calculate node/branch data-dialog select Edit → Node/branch data → Calculate 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.
hasValuehasParentValue
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) * 2would 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 | ^ |
 |
 |
|
10^-2 (= 0.02) |
| Unary plus | + |
|
|
|
+4 |
| Unary minus | - |
|
|
|
-4 |
| Modulo | % |
|
|
|
10 % 4 (= 2) |
| Division | / |
|
|
|
getValue(LENGTH) / 2 |
| Multiplication | * |
|
|
|
getValue("id1") * 100 |
| Addition | + |
|
|
|
getValue("id1") + 10"Two " + "words" |
| Less or equal | <= |
|
|
|
if(getValue(THIS) <= 100, getValue(THIS), 100) |
| Greater or equal | >= |
|
|
|
if(getValue(THIS) <= 100, "A", "B") |
| Less then | < |
|
|
|
if(getValue(THIS) < 100, getValue(THIS), 100) |
| Greater then | > |
|
|
|
if(getValue(THIS) < 100, "A", "B") |
| Equal | = |
|
|
|
if(getValue(THIS) = 100, getValue("id"), getValue("id2")) |
| Not equal | != |
|
|
|
if(getValue(THIS) != "empty", getValue("id1"), 0) |
| And | && |
|
|
|
if(getValue(THIS) < 100 && getValue(THIS) > 50, getValue("id1"), "") |
| Or | || |
|
|
|
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.)
- 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
| 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.
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
