source: branches/stable/HELP_SOURCE/oldhelp/saicalc.hlp

Last change on this file was 18311, checked in by westram, 5 years ago
File size: 9.2 KB
Line 
1#Please insert up references in the next lines (line starts with keyword UP)
2UP      arb.hlp
3UP      glossary.hlp
4
5#Please insert subtopic references  (line starts with keyword SUB)
6#SUB    subtopic.hlp
7
8# Hypertext links in helptext can be added like this: LINK{ref.hlp|http://add|bla@domain}
9
10#************* Title of helpfile !! and start of real helpfile ********
11TITLE           SAI calculator
12
13OCCURRENCE      ARB_NT/SAI/Combine SAIs
14
15DESCRIPTION     The SAI calculator allows to generate new or modify existing SAI data.
16
17                In the top section of the window there are two selection lists:
18                 * the right list contains all existing SAI and
19                 * the left list contains all SAI selected to be used as input of the calculation.
20
21                Next to these lists there are buttons to add/remove SAI to/from the list
22                of selected SAI and other buttons to change the order of that list.
23                To calculate anything you have to select at least one SAI.
24
25                The field labeled "Target SAI" has to contain the name of the destination
26                SAI. To overwrite the data of an existing SAI, select it in the right list and
27                then click the 'Overwrite' button. Otherwise enter the intended name manually.
28
29                The 'Scope' setting selects to which alignments the calculation will
30                be applied:
31                 * Selected alignment: the alignment selected in ARB main window.
32                 * Existing alignments: all alignments listed in alignment admin.
33                 * Common alignments: all alignments with data in all selected input SAIs.
34                 * Target alignments: all alignments with data in "Target SAI".
35
36                The SAI calculator provides several different calculation methods, which can be
37                selected using the "Method"-selector. Afterwards use the EDIT button to configure
38                method specific settings. For details see section about calculation methods below.
39
40                Press the "Calculate" button to run the calculator with the specified settings.
41
42                To view the result it is recommended to load all input- and output-SAI into the
43                arb sequence editor. See LINK{e4_get_species.hlp} if your editor is already
44                up and you'd e.g. like to view a newly created target SAI.
45
46SECTION         Calculation methods
47
48                The SAI calculator supports 4 different calculation methods:
49                    * Translator
50                    * Matrix
51                    * Bool chain
52                    * ACI
53
54                The "Translator" method operates on a single input SAI and translates
55                each input character into a specific output character.
56
57                  In the "Translator" config window you can specify
58                    * sets of input characters (in the "Source" column on the left side)
59                    * one output character for each of these sets (in the "Target" column on the right side)
60                    * the default output character (at bottom)
61
62                The "Matrix" method operates on exacly two input SAIs and translates each
63                combination of two input characters into one output character.
64
65                  In the "Matrix" config window you can specify
66                    * sets of input characters
67                      * for the first SAI (in the top row of input fields)
68                      * for the second SAI (in the leftmost column of input fields)
69                    * one output character for each of combination of these input character sets
70                    * the second row and the second column (both labelled 'Default') combine the
71                      specified character sets with any unspecified character.
72
73                  If fields are left empty, they will fallback to the default - either the default of the
74                  matrix column or the overall default (which defaults to '-').
75
76                  Press the "Normalize" button to simplify the matrix configuration, i.e. sort
77                  columns/rows, combine identical columns/rows and eliminate duplicated default
78                  definitions. This is also done when a configuration gets restored.
79
80                The "Bool chain" method operates on one or multiple input SAIs, which can be combined
81                using different logical operators.
82
83                  In the "Bool chain" config window you can specify
84                    * the single operations (in the list on right side of the window) and
85                    * the used output translation (in the lower left corner of the window).
86
87                  The single operations get defined in the upper left corner of the window and
88                  consist of
89                    * an input translation and
90                    * a boolean operator.
91
92                    The input translation does either define all characters that shall be handled as 'true'
93                    (and the rest will implicitely be handled as 'false') or vice versa.
94                    Note: leaving both fields empty, does completely ignore the input SAI and
95                    results in a boolean sequence containing 'true' in all columns.
96
97                    The first operation ignores its defined boolean operator and does always
98                    display '-->' instead of an operator name. It simply translates the first input SAI
99                    into a boolean sequence.
100
101                    All other operations columnwise combine
102                      * the output of the previous operation and
103                      * the translation of the next input SAI
104
105                    using one of the following logical operators:
106
107                         operator  result true if
108                        --------------------------
109                         AND       both true
110                         OR        any true
111                         XOR       both differ
112                         NAND      any false
113                         NOR       none true
114                         XNOR      both same
115
116                    Use the buttons below the list to ADD new operations or to UPDATE
117                    and DELETE existing operations.
118
119                    Hints:
120                      * to move an existing operation to the end of the list,
121                        select it and then click ADD and DELETE.
122                      * to apply a logical NOT operation, use XOR together with empty
123                        input translations (see above).
124
125                  For the output translation one character has to be defined for true and false state.
126                  It gets applied to the result of the last operation in the chain, before it
127                  is written to the 'Target SAI'.
128
129                The "ACI" method applies the specified LINK{aci.hlp} expression to each SAI column separately.
130                The input passed to the ACI method contains one character for each
131                input SAI (in the order selected at "Source SAIs").
132                The result has to be a single character.
133
134                  Notes/examples:
135                    * you may append '|head(1)' to shorten the output to 1 character (uses just the first character).
136                      That may be useful e.g. in 'minus(1)|head(1)' which decrements digits by 1 while changing '0' to '-'.
137                    * use 'colsplit' to split the input into separate streams (each gets one character).
138                    * to count all non-gap chars from all specified input SAI
139                      use 'remove("-=.")|len'. To improve the readability of the result,
140                      append '|srt(0=-)' to replace all '0' by '-'.
141                    * there are several configurations predefined, most of these use the ACI method (see config icon).
142
143SECTION         Binary SAI
144
145                Binary data is always converted into a string containing the
146                characters '0' and '1' (for "false" and "true").
147                Note: in contrary, ARB_EDIT4 displays binary SAI data using '.' and '+'.
148
149                Any data is automatically written as binary data, if a binary
150                SAI (e.g. 'markerline'; see LINK{phylo.hlp}) is used as target SAI.
151
152                The character '0' is interpreted as "false", all other characters are interpreted
153                as "true".
154
155                Currently there is no way to force binary output data.
156                As workaround you may copy an existing binary SAI and
157                then use it as target.
158
159NOTES           Use the config manager (icon) to store/restore the calculator configuration.
160                This is useful to repeat a calculation after one of its input SAI has been
161                recalculated (e.g. due to modified data).
162
163                Please also refer to LINK{e4_block.hlp} and LINK{e4_modsai.hlp}, if you'd like to modify data
164                of an single SAI, esp. if you want to change only parts of the SAI.
165
166                A comment is written to each calculated SAI alignment (into field "_TYPE") which
167                may be changed using LINK{ad_extended.hlp}.
168                This comment shows the used calculation method and its configuration as
169                stored in the config manager.
170
171EXAMPLES        None
172
173WARNINGS        None
174
175BUGS            No bugs known
Note: See TracBrowser for help on using the repository browser.