source: branches/sina/HELP_SOURCE/source/mg_species.hlp

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

#       sub topics:
SUB     del_list.hlp
SUB     write_field_list.hlp
SUB     mod_field_list.hlp
SUB     mg_xfer_field_of_listed.hlp
SUB     mg_xfer_field_of_sel.hlp

# format described in ../help.readme


TITLE           Compare and Transfer Species Entries

OCCURRENCE      ARB_MERGE/Transfer species

DESCRIPTION     Allows
                        * database searching,
                        * comparison of the two databases,
                        * transferring data from left to right
                        * realigning sequences to new alignment

        Database Searching:

                To perform database searching within the individual databases
                use the left or right part of the 'TRANSFER SPECIES' window for
                source and target database (DB), respectively.

                The database is scanned for 'species' (see LINK{glossary.hlp})
                which contain (or do not contain) the search string within the
                specified 'field' (see LINK{glossary.hlp}). The corresponding
                'species' and the respective 'field' entries are listed in the
                'HIT LIST' subwindow. The number of hits is displayed after the
                'Hits:' prompt.

                Define whether matching or non matching species should be
                listed by pressing the appropriate combination of left
                and right buttons in the 'QUERY TYPE' area. Performing
                multiple searches, define whether the list of 'species'
                should be replaced by the new results, whether newly
                found 'species' should be removed from or appended
                to the existing list.

                Select a 'field' from the 'Fields' subwindow.

                Type the search string to the 'Search string' subwindow.

                Press the 'RUN QUERY' button of the results area.

                See also LINK{searching.hlp} and LINK{search_equal_fields.hlp}.

        Marking species:

                The 'TRANSFER SPECIES' window also provides some functionality
                to interact with species marks (see LINK{mark.hlp}):

                * to mark or unmark all listed species use the corresponding database menu and
                  select to mark or unmark listed species.
                  When the hitlist is empty, these entries will mark or unmark all species.
                * to list all marked species, search for species 'that are marked'.
                * the number of currently marked species is displayed below the two hitlists,
                  on the button behind the number of hits.
                  This button is similar to the one in the ARB main window,
                  and allows to operate with LINK{species_configs.hlp}.

                Species selections may be transferred between both databases
                using LINK{mg_species_configs.hlp}.

        Data Transfer:

                Transfer will always happen from source to target species
                (i.e. from left to right side).

                Select the transfer mode:
                 * "whole species" will copy all fields,
                 * "single field" will copy one single field (selectable, allows to append data) and
                 * "using FTS" will use the "field transfer set" selected below (see LINK{xferset.hlp}).

                   The "using FTS" mode has two flavors (with and w/o sequence data; see section below).
                   The second mode can be used to update/synchronize metadata between two databases
                   containing different alignments (e.g. update metadata of common species from
                   a new SILVA release into your local databases).

                Select the transfer scope:
                 * "selected species" will copy (from) the selected species into
                   a new species or to the species selected in the right-side
                   hitlist.
                 * "listed species" will copy all species listed in the left-side hitlist.

                Click the 'Transfer species' button in the window center to transfer
                according to selected transfer-type and -scope.

                See LINK{save.hlp} for howto save the modified database(s).

SECTION         Overwritten data

                This section describes when and what data will be overwritten
                and when data gets mixed into existing data.

                In "whole species" transfer mode
                 * any existing species (with the same ID, i.e. 'name') will be deleted and
                 * a full copy of each source species will be created.

                The "single field" and "using FTS" transfer modes
                 * will copy from the selected source species to the selected target species
                   when "selected species" scope is used (regardless whether their IDs match or not) or
                 * will copy from each listed species to (a new or already existing) target species
                   with the same ID.

                Some fields are handled special:
                 * the 'name' entry will always be transferred when missing at target.
                 * the 'acc' entry will be transferred when missing at target (and when "using FTS" mode).
                 * whether 'ali_*/data' entries (i.e. the sequence data) will be transferred,
                   depends on the transfer mode:
                   * "whole species" and "using FTS (with seq)" will transfer all existing sequence data
                   * "single field" and "using FTS (w/o seq)" will not transfer any sequence data
                 * all transferred sequence entries will be targeted by alignment adaption (see below).

SECTION         Adapt Alignment

                ARB Merge tries to keep the alignment correct. Normally people
                have inserted new gaps in either the left or right database.
                By entering the ID(s) of some reference species in the input
                box in the upper center of the TRANSFER SPECIES window, the
                program will try to find those species in both databases,
                create a column reference list, and realign all transferred
                sequences.

                To enable this feature, enable the 'Adapt alignment' toggle.

NOTES           You may mix data from source fields with data of existing target fields
                using FTS as follows:

                For example if you have a source field 's1' and an existing destination field 'd1'
                you may merge the contents of these fields (into 'd1') using a simple rule
                transferring 's1' to 'd1' and add one of the following LINK{aci.hlp} expressions:

                    ACI                   does

                    dd;readdb(d1)         prefix content of 's1' in front of 'd1'
                    dd;" ";readdb(d1)     dito, but insert one space
                    readdb(d1);dd         append content of 's1' behind 'd1'
                    readdb(d1);" ";dd     dito, but insert one space


EXAMPLES        For general examples of database searching see LINK{sp_search.hlp}.

WARNINGS        The data will always be transferred from the source DB to
                the target DB.

                If you want to align sequences during transfer, it is recommended
                that the left database has fewer gaps than the right one.

                Entries in the target database will be overwritten w/o further consent
                (applies to single transferred fields and complete transferred species).

BUGS            No bugs known