Help - Importing node/branch data

Besides importing node/branch data from tree files (see Adding support values) TreeGraph 2 also allows to import annotations from tables in text format as they can be generated by every spread sheet application. The only condition is that one column of that table contains unique values that are found in one node/branch data column (e.g. Unique node names, node names, hidden node/branch data, ...) of the tree into which the table shall be imported.

You can access this function by selecting "Import table as node/branch data as table..." from the file menu or with the keyboard shortcut Shift + F9.

This article describes this feature for the latest version of TreeGraph 2. For older versions the following articles are available:
Importing node/branch data (until 2.0.49), Importing node/branch data (until 2.11.1)

In contrast to previous versions, TreeGraph 2.0.50 and later is able to identify the target nodes for the import by any node/branch data column and not just by the Unique node names. Since TreeGraph 2.12.0 it is possible to select any column of the table as the key column and not only the first.

How is the table imported?

Identifying according table rows and tree nodes

One column of the imported table is selected to be the key column and must contain values (keys) that identify the node of the tree onto which all other columns of that row shall be imported. The values in this column must be unique, i.e. there must not be two rows containing the same value in the key column. (Note that the question, if two keys are equal depends on the options you chose in the compare options panel of the second dialog. See below.)

When importing a table you are asked which node/branch data column in the tree shall be used to identify the nodes to attach the data to. (See dialog description below.) Here you should select the node/branch data column of the tree which contains the same values as the key column of your table. The entries in this node/branch data column do not have to be unique. If multiple tree nodes have the same value in that column the data from the according key column is attached to all of that nodes.

Replacing the contents of a node/branch data column

Since the first extended version of this table import function was released (TreeGraph version 2.0.50) the apply name table function used to replace values of a node/branch data column (e.g. lab codes of sequences by real taxon names) was removed from the application because it is now included in this function. To perform such a replacement you need a table with at least two columns (one containing the old and another containing the new values for the node/branch data to be processed. Now you only have to select the same node/branch data column for the tree key column in using the second dialog (see below and for the target node/branch data column in the third dialog. (The target nodes of the import will of course be identified before there values are changed to make this work.)

The dialogs

This feature uses three dialogs which are displayed one after the other. The first allows you to choose the text file that contains the table to be imported, the second allows to connect the key column from the table with a node/branch data column of target tree and the third lets you select into which node/branch data columns the annotations contained in the table shall be copied.

The "Table file"-dialog

The file dialog

This dialog is displayed first and is used to select the text file that contains the table to be imported and to specify further options on how the heading of the table looks like. Click the Next > button to get to the key columns dialog.

File

Select the text file that contains the table to be imported here.

Table preferences

You give information on the structure of the text file you want to import here.

Values separated by: Here you can choose the column separator that has been used in the text file (usually tab or comma).
Number of lines to skip before heading or data: If your file contains additional text before the table starts, you can specify the number of initial lines that shall be ignored when reading the data here. (An optional line containing column headings (see below) would not be counted as an ignored line here.)
First line (after skipped lines) contains column headings: Check this option, if the first line of your table contains column headings and not data. (These headings are than suggested as node/branch data IDs, when you select the node/branch data columns of your tree to store the data in the next step.)

The "Key columns"-dialog

The key columns dialog

This dialog allows to link the key column from the table to a node/branch data column of the tree. Matching the values of these two columns allows to determine the nodes to which the data from each imported table row will be attached. Click the Next > button to get to the column import dialog.

Key column in table

Here you can select one of the columns of the table to be imported that contains the same values as a node/branch data column in the tree. The entries in the rows of this column must be unique.

Key column in tree

From this drop down menu you should select the node/branch data column from the tree which contains the same values as the previously selected column (key column) of your table.

Compare options

The options available here allow to define when values from the key columns of the table and the tree are considered to be matching. The following options are available:

Ignore leading and trailing white spaces: Check this option, if you want the key "NodeA" to be considered a identical to " NodeA" or "NodeA ".
Distinguish between space (" ") and underscore ("_"): Check this option, if you want the key Node A to be considered a identical to Node_A.
Case sensitive: Check this option, if you want the key Node A to be considered a identical to Node a or NODE A.
Parse numeric values if possible: Check this option, if you want the key 200 to be considered a identical to 200.0 (e.g., English decimal separator), 200,0 (e.g., German decimal separator) or 2E2 (2 · 10²).
- Both decimal separators are supported here. Thousand separators are not allowed, because it would not possible to distinguishing e.g. between "1,236" meaning 1236 in e.g. English and "1,236" meaning 1.236 in e.g. German. In case you have a data file containing thousand separators, use the according format function a spread sheet application (e.g. OpenOffice Calc) or the replace function of a text editor to remove them before opening the file with TreeGraph.
- If any value can not be parsed as a number, it is still treated as a textual key.

The "Column import"-dialog

The column import dialog

Depending on how many columns are contained in the text (additional to the key column) there will be a combo box for each column that lets you select the node/branch data column where you want to import the data. You can select existing to be overwritten or new columns here. If you select a new group of labels or a new hidden node/branch data column you also have to specify an ID in the text field right of the according combo box. (If your table contains a row column and you checked the according option in the previous dialog the headings will be suggested as IDs here.)

Note that the target for the previously selected key column can not be edited, since it will not be imported.