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

#       sub topics:
#SUB     subtopic.hlp

# format described in ../help.readme


TITLE           SAI calculator

OCCURRENCE      ARB_NT/SAI/Combine SAIs

DESCRIPTION     The SAI calculator allows to generate new or modify existing SAI data.

                In the top section of the window there are two selection lists:
                 * the right list contains all existing SAI and
                 * the left list contains all SAI selected to be used as input of the calculation.

                Next to these lists there are buttons to add/remove SAI to/from the list
                of selected SAI and other buttons to change the order of that list.
                To calculate anything you have to select at least one SAI.

                The field labeled "Target SAI" has to contain the name of the destination
                SAI. To overwrite the data of an existing SAI, select it in the right list and
                then click the 'Overwrite' button. Otherwise enter the intended name manually.

                The 'Scope' setting selects to which alignments the calculation will
                be applied:
                 * Selected alignment: the alignment selected in ARB main window.
                 * Existing alignments: all alignments listed in alignment admin.
                 * Common alignments: all alignments with data in all selected input SAIs.
                 * Target alignments: all alignments with data in "Target SAI".

                The SAI calculator provides several different calculation methods, which can be
                selected using the "Method"-selector. Afterwards use the EDIT button to configure
                method specific settings. For details see section about calculation methods below.

                Press the "Calculate" button to run the calculator with the specified settings.

                To view the result it is recommended to load all input- and output-SAI into the
                arb sequence editor. See LINK{e4_get_species.hlp} if your editor is already
                up and you'd e.g. like to view a newly created target SAI.

SECTION         Calculation methods

                The SAI calculator supports 4 different calculation methods:
                    * Translator
                    * Matrix
                    * Bool chain
                    * ACI

                The "Translator" method operates on a single input SAI and translates
                each input character into a specific output character.

                  In the "Translator" config window you can specify
                    * sets of input characters (in the "Source" column on the left side)
                    * one output character for each of these sets (in the "Target" column on the right side)
                    * the default output character (at bottom)

                The "Matrix" method operates on exacly two input SAIs and translates each
                combination of two input characters into one output character.

                  In the "Matrix" config window you can specify
                    * sets of input characters
                      * for the first SAI (in the top row of input fields)
                      * for the second SAI (in the leftmost column of input fields)
                    * one output character for each of combination of these input character sets
                    * the second row and the second column (both labelled 'Default') combine the
                      specified character sets with any unspecified character.

                  If fields are left empty, they will fallback to the default - either the default of the
                  matrix column or the overall default (which defaults to '-').

                  Press the "Normalize" button to simplify the matrix configuration, i.e. sort
                  columns/rows, combine identical columns/rows and eliminate duplicated default
                  definitions. This is also done when a configuration gets restored.

                The "Bool chain" method operates on one or multiple input SAIs, which can be combined
                using different logical operators.

                  In the "Bool chain" config window you can specify
                    * the single operations (in the list on right side of the window) and
                    * the used output translation (in the lower left corner of the window).

                  The single operations get defined in the upper left corner of the window and
                  consist of
                    * an input translation and
                    * a boolean operator.

                    The input translation does either define all characters that shall be handled as 'true'
                    (and the rest will implicitely be handled as 'false') or vice versa.
                    Note: leaving both fields empty, does completely ignore the input SAI and
                    results in a boolean sequence containing 'true' in all columns.

                    The first operation ignores its defined boolean operator and does always
                    display '-->' instead of an operator name. It simply translates the first input SAI
                    into a boolean sequence.

                    All other operations columnwise combine
                      * the output of the previous operation and
                      * the translation of the next input SAI

                    using one of the following logical operators:

                         operator  result true if
                        --------------------------
                         AND       both true
                         OR        any true
                         XOR       both differ
                         NAND      any false
                         NOR       none true
                         XNOR      both same

                    Use the buttons below the list to ADD new operations or to UPDATE
                    and DELETE existing operations.

                    Hints:
                      * to move an existing operation to the end of the list,
                        select it and then click ADD and DELETE.
                      * to apply a logical NOT operation, use XOR together with empty
                        input translations (see above).

                  For the output translation one character has to be defined for true and false state.
                  It gets applied to the result of the last operation in the chain, before it
                  is written to the 'Target SAI'.

                The "ACI" method applies the specified LINK{aci.hlp} expression to each SAI column separately.
                The input passed to the ACI method contains one character for each
                input SAI (in the order selected at "Source SAIs").
                The result has to be a single character.

                  Notes/examples:
                    * you may append '|head(1)' to shorten the output to 1 character (uses just the first character).
                      That may be useful e.g. in 'minus(1)|head(1)' which decrements digits by 1 while changing '0' to '-'.
                    * use 'colsplit' to split the input into separate streams (each gets one character).
                    * to count all non-gap chars from all specified input SAI
                      use 'remove("-=.")|len'. To improve the readability of the result,
                      append '|srt(0=-)' to replace all '0' by '-'.
                    * there are several configurations predefined, most of these use the ACI method (see config icon).

SECTION         Binary SAI

                Binary data is always converted into a string containing the
                characters '0' and '1' (for "false" and "true").
                Note: in contrary, ARB_EDIT4 displays binary SAI data using '.' and '+'.

                Any data is automatically written as binary data, if a binary
                SAI (e.g. 'markerline'; see LINK{phylo.hlp}) is used as target SAI.

                The character '0' is interpreted as "false", all other characters are interpreted
                as "true".

                Currently there is no way to force binary output data.
                As workaround you may copy an existing binary SAI and
                then use it as target.

NOTES           Use the config manager (icon) to store/restore the calculator configuration.
                This is useful to repeat a calculation after one of its input SAI has been
                recalculated (e.g. due to modified data).

                Please also refer to LINK{e4_block.hlp} and LINK{e4_modsai.hlp}, if you'd like to modify data
                of an single SAI, esp. if you want to change only parts of the SAI.

                A comment is written to each calculated SAI alignment (into field "_TYPE") which
                may be changed using LINK{ad_extended.hlp}.
                This comment shows the used calculation method and its configuration as
                stored in the config manager.

EXAMPLES        None

WARNINGS        None

BUGS            No bugs known
