source: trunk/HELP_SOURCE/source/move_groups.hlp

#       main topics:
UP      arb.hlp
UP      glossary.hlp
UP      treeadm.hlp

#       sub topics:
#SUB     subtopic.hlp

# format described in ../help.readme


TITLE           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 LINK{keeled_groups.hlp}, but
                        this is not yet implemented (will be fixed with bug mentioned below).

SECTION         Target group name

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

                Compared with standard LINK{aci.hlp}, 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

SECTION         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 LINK{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 LINK{group_search.hlp} 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 LINK{http://bugs.arb-home.de/ticket/512})