Main topics:

SAI calculator

OCCURRENCE
DESCRIPTION
Calculation methods
Binary SAI
NOTES
EXAMPLES
WARNINGS
BUGS

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 ´Load species/SAI into running editor´ if your editor is already up and you'd e.g. like to view a newly created target SAI.

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 ´ARB Command Interpreter (ACI)´ 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).

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 ´ARB_PHYLO - Create filters by base frequency´) 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 ´ARB_EDIT4 Block Operation´ and ´Modify SAI range´, 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 ´SAI Administration´. This comment shows the used calculation method and its configuration as stored in the config manager.