#Please insert up references in the next lines (line starts with keyword UP) UP arb.hlp UP glossary.hlp #Please insert subtopic references (line starts with keyword SUB) #SUB group_rename.hlp # Hypertext links in helptext can be added like this: LINK{ref.hlp|http://add|bla@domain} #************* Title of helpfile !! and start of real helpfile ******** TITLE Search taxonomic groups OCCURRENCE ARB_NT/Tree/Search groups DESCRIPTION Allows to find taxonomic groups in trees. First select which trees shall be searched: - current tree (displayed in main window) - selected trees (use the '(select)' button to LINK{group_trees.hlp}) - all trees Standard search mode is to 'list' all groups that 'match' the query. Alternatives are: - selecting 'dont match' instead of match will invert the overall query - selecting 'add', 'keep' or 'remove' instead of 'list' will allow to combine the results of multiple consecutive searches. Query expressions are handled similar to those in LINK{sp_search.hlp}. While species-search operates on database fields, groups-search mainly operates on values which are calculated on-the-fly. Please refer to LINK{searching.hlp} for general information about query expression syntax and about the combination of multiple query expressions. For details about the search criteria available for group search see section below. Press ENTER or click 'Search' to start the search. The HITLIST will display all matching groups. The number of hits is shown above the HITLIST. Click onto a result to select the group in the main window. Double click or press ENTER on a result to expand or collaps the selected group. Below the HITLIST is a radio button which allows to choose the order (and the content) of the displayed results. The following criteria are available for sorting: - by name: sort alphabetically by name of group - by nesting: sort numerically by level of group nesting (top level groups like 'Bacteria' have level 0, their direct child group have level 1, etc.) - by size: sort numerically by size (number of group-members) - by marked: sort numerically by number of marked species (will not automatically update if you change marks; rerun 'Search' to do so) - by marked%: similar to mark, but uses percentage of marked - by treename: sort alphabetically by name of tree - by treeorder: sort by tree (in order defined by LINK{treeadm.hlp}) - by hit: sort by hit-description (the hit description tells you why an item was hit by query) - by cluster: only has effect for duplicate search (see section below) - by AID (see below) - by keeled: keeled groups at top (see LINK{keeled_groups.hlp}) - reverse: reverts previously selected sort order The most recently selected criterion will be most authoritative, but previously selected criteria still remain active, i.e. when you first sort by name and afterwards by treename, the results will group by trees, but inside each tree-section groups are sorted by name. The 2 buttons above the HITLIST allow to modify it: * 'Remove' allows to manually remove unwanted hits from the result list (useful before applying one of the actions listed in the next section). * 'Clear' empties the result list. SECTION Search criteria Group search supports the following search expressions: - 'groupname' matches against the name of each group - 'parent' matches against the name of the direct parent group of the queried group - 'parent (any)' is true if any parent group of the queried group matches the given expression - 'parent (all)' is true if all parent groups of the queried group match the given expression (a common use of this is to check for exclusion. To e.g. check that no parent group matches '*bacteria*', check that all parents mismatch '*bacteria*') - 'nesting' allows to query the nesting-level of groups (top-level-groups like 'Bacteria' have a nesting level of 0 (zero), their direct child-groups have a nesting level of 1, ...) - 'folded' allows to query for folded/unfolded groups (possible values are 0 and 1) - 'size' matches against the groupsize (i.e. against the number of species inside a group and its subgroups) - 'marked' queries against the number of marked species inside a group - 'marked%' queries against the percentage of marked species inside a group - 'zombies' queries against the number of zombie species inside a group - 'AID' queries against the average ingroup distance (see following section) - 'keeled' queries against the keeled state (0=normal,1=keeled upper son,2=keeled lower son; see LINK{keeled_groups.hlp}) SECTION Average ingroup distance (AID) For each group the average distance of all possible pairs of species inside that group is retrieved from the tree structure and is provided as criterion for group-search and to order results. The distance of two species is defined as the sum of the lengths of all branches connecting the two species. SECTION Duplicate search Next to the 'Search' button is a selector which allows to restrict the listed groups by analysing whether they are duplicates or not. The different available modes are: - 'no' = deactivate duplicate search - 'duplicate groups only' = activate duplicate search - 'unique groups only' = list all group not reported by duplicate search The 'Configure' button provides detailed settings for duplicate search: - Min. size of duplicate cluster The minimum number of groups, which have to be strictly consistent with any given duplication criteria (=core of cluster). If that min. size isn't found, these groups will not be listed in results. - Search duplicates Defines where duplicates are expected to occur. - inside same tree All groups of a cluster have to be members of the same tree. Duplicates in other trees probably form their own cluster. - in different trees The core of the cluster will only consist of groups from different trees (one hit per tree) and the whole cluster will be discarded, if the required minimum size isn't reached. For the final result all other duplicate will be added, i.e. there may be more than one hit per tree. - anywhere - Ignore case? Define whether to ignore case when matching group names, words or when checking against the list of ignored words. - Duplicates are names that Defines how duplicate groups are detected. Either - by matching the whole name or - by matching single/multiple words. - Min. number of matching words If fewer words match between two compared groupnames, they are counted as mismatch. Hits with more matching words are preferred over such with fewer words. - Word separators Defines characters which separate words. Should normally contain a SPACE character. - Ignored words Specifes a list of words that will be completely ignored when matching wordwise. Sorting results 'by cluster' will list related duplicate-groups next to each other. It will also add a new column showing the unique IDs of each cluster of groups. SECTION Working with listed groups Right of the HITLIST are several buttons allowing to work with the found results: * 'Rename ...' allows to LINK{group_rename.hlp}. * 'Expand listed' will expand all listed groups and their parent groups. * 'Expand listed collapse rest' does the same and additionally folds all other groups. * 'Expand parents' will expand the parents of all listed groups, i.e. all listed groups will become visible. * 'Collapse listed' will collapse all listed groups. * The button 'Mark', 'Unmark' and 'Inv' allow to change marks of species contained in listed groups. Use the option-menu below these buttons and select - 'selected' to operate on all species contained in the currently selected group, - 'any listed' to operate on all species contained in ANY of the listed groups, - 'all listed' to operate on all species contained in ALL of the listed groups or - 'database' to operate on all species in the database. * 'Destroy selected group' will delete that group from the tree. Be aware that this action is currently irreversible (see BUGS below). * 'Destroy all listed groups' will delete all groups currently listed in the HITLIST. NOTES Please configure auto-focus options in LINK{nt_tree_settings.hlp} (esp. auto-unfold) to improve the usability of the group search. Use the config manager icon (see LINK{prop_configs.hlp}) to store/restore group search and rename settings. EXAMPLES Common combinations of expanding and collapsing groups: * to collapse ALL groups of ALL searched trees press - 'Clear' to empty the HITLIST and - 'Expand listed collapse rest'. * to expand parent groups of listed and fold the rest press - 'Expand listed collapse rest', - 'Collapse listed' and - 'Expand parents'. Common combinations for marking specific group members: * to mark all species NOT contained in all listed groups use - 'Mark' + 'any listed' followed by - 'Unmark' + 'all listed' WARNINGS Searching for duplicates with wordwise mode and expecting only a few words (e.g. 2 words for tree in SSURef_NR99_128_SILVA), may take very, very long. Expecting more words will speed up the search. BUGS UNDO does not work for deleting groups (http://bugs.arb-home.de/ticket/480)