Google
More docs on the ARB website.
See also index of helppages.
Last update on 21. Feb 2020 .
Main topics:
Related topics:

Move groups

OCCURRENCE

ARB_NT/Tree/Move groups

 

DESCRIPTION

Copy or add the internal group labels from one tree to another.

Select the source tree (containing groups to move) in the left selection list and the target tree in the right selection list.

Select which 'Groups to move':

  • 'all groups' does copy all groups
  • 'groups with marked' does only copy groups containing at least one marked species (see BUGS)

Choose how to handle 'Existing target groups':

  • 'remove existing groups' will remove all groups existing in target tree
  • 'keep ...' will keep groups existing in target tree: if a group gets transferred to an already named target node, the resulting groupname will be "newname [was: oldname]". If newname and oldname are identical, the existing name will not change. Non-overwritten groups will persist, new groups will be inserted.

The 'Target groupname:' input field allows to specify an ACI which will be used to generate the name used in destination tree (details see separate section below).

The algorithm will compare subtrees of both trees and calculate a score based on differences between two subtrees (regarding contained species).

Based on that score

  • each transferred group will be placed at the destination node with the best score (i.e. with the lowest penalty).
  • if several groups would be placed at the same destination node, the group with lowest penalty will get inserted and all other groups will get skipped, i.e. will not be inserted into the destination tree. A log entry will be written for all skipped groups.

The single base penalties used to calculate that score can be defined in the top section of the "Move groups" window:

Basically there are 4 different kinds of penalties:
  • a penalty for each former member of a group which will no longer be a member of the group after it has been transferred to the destination tree (=ingroup penalties).
  • a penalty for each new member in the transferred group, which was member of the source tree, but wasn't member of the source group (=outgroup penalties).
  • a penalty for each member of the source group, which is no member of the target tree (=unknown penalty).
  • a penalty for using the keeled group (=keeling penalty).

The ingroup- and outgroup-penalties are available in 2 flavors:
  • absolute penalties which are awarded per species and
  • relative penalties which are awarded relative to the group-size.

The unknown penalty is awarded per species.

The ingroup- and outgroup-ratios used for the relative penalty-flavors are caluclated as follows:

  • ingroup ratio = former members in new group / former members
  • outgroup ratio = new members in new group / members of new group

It's possible to specify a lower limit for allowed ingroup-ratios and an upper limit for allowed outgroup-ratios. Please note that this feature is experimental! The algorithm will accept worser penalties (i.e. worser group placements) to force these limits.

Example for useful limit:
  • ingroup 100-100; outgroup 0-0 => only transfer perfectly matching groups

For each group inserted and/or removed from destination tree, a log entry is generated as well, either

  • a basic entry, if a group perfectly matches into the new tree or
  • a detailed entry showing
    • the mismatch penalty,
    • ingroup (remaining % / old groupsize),
    • outgroup (inserted % / new groupsize) and
    • a warning if the best penalty did match the "rest of the tree".

    Note:
    in the latter case the algorithm should insert ´Keeled groups´, but this is not yet implemented (will be fixed with bug mentioned below).

 

Target group name

Specifying an ACI expression at 'Target groupname:' allows to customize the groupnames used in the target tree.

Compared with standard ´ARB Command Interpreter (ACI)´, the ACI used here knows several extension commands:

  • groupname: inserts the group name as used in source tree
  • penalty: inserts the penalty calculated for the group transfer
  • ingroup: inserts the ingroup-ratio in percent
  • outgroup: inserts the outgroup-ratio in percent
  • unknown: number of unknown species in source group
  • oldsize: inserts the size of the source group (ignores unknown species, i.e. species that are no members of the target tree)
  • newsize: inserts the size of the target group
  • keeled: 1 if group matched versus keeled set, 0 otherwise

 

Negative penalties

  • a negative penalty is a bonus.
  • a bonus is not allowed at in-/outgroup penalties. These penalties even have to differ from zero (at least one of them). To e.g. effectively prefer ingroup criteria over outgroup criteria, use a very small value for outgroup relative penalty, e.g. 0.000001
  • bonuses are (currently) allowed for
    • Unknown members (quite useless)
    • Keeling => will prefer keeled group over normal group


 

NOTES

Currently moving node info depends on placement of the tree root. Setting the root in the destination tree similar to the root in the source tree can greatly improve results of node transfer.

 

BUGS

ARB sets the root-node of the destination tree, but often fails to find the best possible node (see also http://bugs.arb-home.de/ticket/451)

When testing for marked species currently the target group is tested.

When moving groups, several other node-attached data is moved as well (e.g. angles or linewidth-attributes). These attributes currently get overwritten at target-positions with the attributes found at source positions.

 

EXAMPLES

There is an example ACI (stored in the config manager) and named '*report2name'. That ACI will add a fixed prefix and write the resulting penalty as suffix to the destination groupname.

Using ´Search taxonomic groups´ to find these groups, e.g. allows to

  • search for specific transfer penalties,
  • select and review such groups inside the topology,
  • manually check poorly placed groups (e.g. mark species contained in group udn compare with source group in 2nd window) and then either correct or delete such groups.

To restore the original groupnames of all currently listed groups, the config manager (in the group search window) provides a predefined config named '*undo_groupXfer_report', containing an ACI for 'Rename' which removes the prefix and suffix added above.

Restoring original name might be used to "mark" these groups as 'accepted', while you still need to decide what to do with the remainder of the transferred groups.

 

WARNINGS

It's slow.. (examples see http://bugs.arb-home.de/ticket/512)