source: branches/lib/HELP_SOURCE/source/saicalc.hlp

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