

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 TREEFINDER'S LANGUAGE (TL)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TL is a general-purpose programming language with numerous specialized tools to
handle biological data. It serves as a programming interface of the TREEFINDER
program. This manual is giving an overview of TL.

What makes TL different from other programming languages is that it supports a
variety of programming styles. At any time, a programmer can choose the
programming style that is the most powerful in a given situation.

The following material is still incomplete.


???. CONTENTS
=============

???. CONTENTS
???. EXPRESSIONS
???. STACK-ORIENTATED PROGRAMMING
???. IMPERATIVE PROGRAMMING
???. FUNCTIONAL PROGRAMMING
???. RULE-BASED PROGRAMMING
???. OPERATOR LIST
???. FUNCTION LIST


???. EXPRESSIONS
================

TL is about evaluating expressions. Expressions can represent data as well as
programs. An expression is a piece of a TL program text that can be translated
into a data structure in computer memory, but we will also use the term for the
latter.

TL has the following types of expressions:

   Type            Example
  -----------------------------------
   Void            ~Void~ or nothing
   Boolean         True or False
   Integer         123
   Real            1.23e4
   Stream
   RealArray
   String          "hello world!"
   Symbol          x
   Routine
   Composed        f[x,y]

There are atomic types and composed types. A 'Composed' expression is
recursively composed of either atomic or composed expressions. All other types
are atomic. Most types are 'writable' and can be written as a piece of program
text. Expressions of the types 'Stream' and 'Routine', however, exist only in
computer memory.

The composed expression f[x,y] consists of the 'components' f, x and y. The f is
called the 'head', whereas the x and y are called the 'contents' or 'arguments'.
A composed (expression) has one and only one head and may have an arbitrary
number of contents. In a textual representation the contents must be separated
by commas.

For frequently used heads exist operator notations. This helps writing concise
TL texts and improves their readability by humans. For example, the expression
a+b with the operator + is equivalent to Add[a,b]. Operators are summarized in
the operator list section of this manual.

Important heads are:

    Head         Operator      Example
  -------------------------------------------
    List         { }           {1,2,3}
    Chain        :             1:100
    Rule         ->            x->y
    Function     << >>         <<Dup,Add2>>
    Add          +             a+2
    Mul          *             a*2
    Let          :=            x:=2
    Set          =             x=2

Some heads represent data while others are commands. Phylogenetic trees and
sequence alignments, for example, are mostly built from 'List' and 'Chain'
expressions:

 {{"cow":0.08,"sheep":0.07}:0.12,"horse":0.18,"bear":0.16}         %% a tree

 {"cow":"TCCAG","sheep":"TCCCG","horse":"TTC-G","bear":"TTCGG"}    %% sequences

The text behind %% is comment.

A 'Void' expression is often implicitly assumed where the absence of an
expression would be syntactically incorrect, otherwise. For example, the second
content of f[x,,y] or x::y is a 'Void' expression.

TL expressions are meant to be interpreted by the TL interpreter. This is a
state machine that changes its state depending on the TL expressions it reads
from an input stream. We say, the interpreter evaluates expressions. In addition
to changing the interpreter state, the evaluation of expressions may have
side-effects, which is anything else happening. A typical side-effect is the
writing of results into an output stream. If the interpreter is run
interactively, some aspects of its state are reported to a frontend where we
can see them.


???. STACK-ORIENTATED PROGRAMMING
=================================

Once launched, TREEFINDER is waiting for input at the TL prompt:

 |TL>

For example, one can type there

 |TL>3+4

and after pressing RETURN the result

 |1: 7
 |TL>

will appear on the 'stack'. TREEFINDER is waiting again.

More complicated expressions are possible. Entering

 |1: 7
 |TL>3*(4+5*6)

gets one correctly

 |2: 7
 |1: 102
 |TL>

The stack is the place where the the TL interpreter stores the pieces of data it
is working with. It behaves like a stack of books. The last book placed on the
stack is the first book that will later be removed. On the screen, the contents
of the stack are shown together with their level numbers above the prompt. The
most recent result appears at level 1, while the result of the previous
calculation is at level 2. We say that stack level 1 is 'topmost'.

Things on the stack can be used for further calculations. Typing the command

 |2: 7
 |1: 102
 |TL>Add

will add them:

 |1: 109
 |TL>

There is a third way to add numbers:

 |1: 109
 |TL>Add[88,11]

gives

 |2: 109
 |1: 99
 |TL>

This is the functional form. 'Add' is the function. Within the square brackets
it has arguments, which are separated by commas. The special thing about TL is
that functions can operate on the stack as well as on argument lists.

Evaluating the function Add[88,11] is equivalent to evaluating the following
sequence of expressions:

 |2: 109
 |1: 99
 |TL>88,11,Add

returns

 |1: 307
 |TL>

Oh - it is not quite equivalent: ALL numbers on the stack have now been added.
Invoked in the functional form, the 'Add' function will only see the numbers
from its argument list. In its raw form, however, it will add the whole stack.

The command

 |1: 307
 |TL>Clear

clears the stack. Trying again

 |TL>88,11,Add

gets us

 |1: 99
 |TL>

as expected.

Operator expressions like 4+5*6 are first translated by the interpreter into a
functional form Add[4,Mul[5,6]], and then into a sequence of raw expressions.
Stack-orientated programming is trying to avoid such translations and is
therefore the programming style that produces the fastest programs.

To keep further examples concise, I am here introducing the following short
notation:

 3,4,5,Add   -->   12
 3,4,5   -->   3,4,5
 3,4,5,Clear   -->   ()

 4+5*6   -->   34
 Add[4,Mul[5,6]]   -->   34
 5,6,Mul,4,Add   -->   34

The symbol --> is not part of TL and reads "evaluates to" or "gives". Entering
the expressions on the left side will produce the stack on the right side, with
the topmost expression shown last. The () denotes an empty stack. In some cases
the stack must empty before any expressions are entered.

Once having pushed a couple of things on the stack, one might want to rearrange
or remove them:

 x,y,z   -->   x,y,z
 x,y,z,Dup   -->   x,y,z,z
 x,y,z,Swap   -->   x,z,y
 x,y,z,Drop   -->   x,y
 x,y,z,Clear   -->   ()

The following functions manipulate the stack:

 Stack          lists the things on the stack
 StackLength    counts the things on the stack
 Clear          removes everything from the stack
 Drop           removes the topmost thing from the stack
 Swap           exchanges levels 1 and 2
 Roll           moves a specified level to the top
 Pick           copies a specified level to the top
 Dup            duplicates the topmost thing
 DupN           duplicates a specified number of topmost things
 ListN          collects a specified number of things into a list
 Build          builds an expression from components
 Unbuild        dissolves an expression into its components

Descriptions are given in the function list section of this manual.


???. IMPERATIVE PROGRAMMING
===========================

Imperative programming is the programming style that most programmers are
familiar with. An imperative program consists of a sequence of instructions
telling the computer step by step what to do.

The following TL program computes the average of a list of numbers:

 {1,2,3,4,5},
 Dup,Length,Swap,'Add,Apply,Swap,Div

 -->   3

To run the program, copy the program text (without the --> ...) into a new text
file and save it on your disk. Then, select that file through the frontend menu
'Kernel|Load TL Script ...' and soon the result 3 will appear on the stack.

Alternatively, you can copy the program text into a new text window of the
TREEFINDER frontend and press the 'Run TL Script' button. Again, the result 3
is pushed on the stack. Using the arrow buttons will get you back to your
program text.

Pieces of code can be stored in variables and reused multiple times:

 f:=<<Dup,Length,Swap,'Add,Apply,Swap,Div>>,
 {1,2,3,4,5},f,
 {1,2,3,4,5,6},f,
 f[{1,2,3,4,5,6,7}],
 Forget[f]

 -->   3,3.5,4

In this example, the sequence of our averaging commmands is stored as a
function f (line 1), which is then applied to three different lists of numbers
(lines 2 to 4). The program returns three results on the stack. The function f
can be used both in a stack-orientated manner (lines 2 and 3) as well as in a
functional manner (line 4). After the calculation, the definition of f is being
forgotten (line 5), which saves us memory, and in some cases also problems.
Please note that some operations return expressions while others do not. In
our example, only the lines 2 to 4 produce the results that remain on the stack.

Imperative programs typically use variables to store intermediate results. Our
averaging program can alternatively be formulated like this:

 list:={1,2,3,4,5},
 sum:=list@Add,
 len:=Length[list],
 sum/len,
 Forget[{list,sum,len}]

 -->   3

In line 4 the average is computed from intermediate results stored in the
variables 'sum' and 'len'.

Most programmers are familiar with the concept of local variables. Declaring
'list', 'sum' and 'len' as local variables within a 'Scope' removes the need to
forget them after the calculation:

 Scope[{list,sum,len},
  list={1,2,3,4,5},
  sum=list@Add,
  len=Length[list],
  sum/len
 ]

 -->   3

Finally, one might want to define a reusable averaging function f and provide
the list as an argument:

 f[list]:=<<Scope[{sum,len},sum=list@Add,len=Length[list],sum/len]>>,
 f[{1,2,3,4,5}]

 -->   3

You might have already noticed that TL has two different assignment operators,
namely ':=' and '='. The ':=' belongs to the 'Let' function, whereas the '='
belongs to 'Set'.

The TL interpreter maintains a list of definitions in computer memory. Each
definition is a pair of a symbol and some expression to be denoted by that
symbol. If nothing is defined, a symbol will evaluate to itself:

 x   -->   x            %% {}

After the comment symbol %% the invisible definition list is shown, which does
not yet contain any entry for x. The 'Let' function prepends a new definition
to the definition list:

 x:=17   -->   ()            %% {x->17}

Now, the evaluation of the symbol x will return the expression 17 that is bound
to that symbol:

 x   -->   17            %% {x->17}

Forgetting the symbol will remove its definition from the list:

 Forget[x]   -->   ()            %% {}
 x   -->   x

Multiple calls of 'Let' with the same symbol will each time prepend a new
definition to the definition list while older definitions are pushed behind. If
there is more than one definition for a symbol, the interpreter will use the
frontmost. Forgetting will also apply to the frontmost definition. Please note,
what happens:

 x   -->   x                     %% {}
 x:=3   -->   ()                 %% {x->3}
 x+x   -->   6
 x:=4   -->   ()                 %% {x->4,x->3}
 x+x  -->   8
 Forget[x]   -->   ()            %% {x->3}
 x   -->   3
 Forget[x]   -->   ()            %% {}
 x   -->   x

A definitions can be hidden by a newer definition, and it will reappear when
the hiding definition is removed.

So far, so good. But what is the 'Set' function good for?

The 'Set' function updates an already existing definition. Only if there is
no entry for that symbol, it will prepend a new definition to the list:

 x   -->   x                     %% {}
 x=3   -->   ()                  %% {x->3}
 x+x   -->   6
 x=4   -->   ()                  %% {x->4}
 x+x   -->   8
 Forget[x]   -->   ()            %% {}
 x   -->   x

In TL, an assignment always addresses a certain entry in the definition list
that the programmer must have in mind when writing a program. This is important,
but not really difficult.

With the function 'Create' one can finally create and prepend empty definitions
that hide previous definitions, if such exist:

 x   -->   x                     %% {}
 x:=3   -->   ()                 %% {x->3}
 x+x   -->   6
 Create[x]   -->   ()            %% {x->x,x->3}
 x   -->   x
 Forget[x]   -->   ()            %% {x->3}
 x   -->   3
 Scope[{x},x],x   -->   x,3
 Scope[{x},x=2,x],x   -->   2,3
 Scope[{x:=2},x],x   -->   2,3
 x   -->   3
 Forget[x]   -->   ()            %% {}
 x   -->   x

This is the mechanism to make variables local: the 'Scope' function locally
creates empty or newer definitions for the local variables specified in the list
to hide older definitions for these names. Its other arguments are then
evaluated one after another under the current definitions. We use '=' to assign
values to local variables because ':=' would create new definitions that were
not managed and afterwards removed by the 'Scope' function.

TL provides elements to control the program flow, i.e. functions to construct
decisions and loops. Basically, they are the same as in many other computer
languages.

Flow control is based on tests that either give 'True' or 'False':

 Scope[{x:=4}, x>3 ]   -->   True
 Scope[{x:=2}, x>3 ]   -->   False

The function 'If' with operator symbol '?' decides:

 Scope[{x:=4}, If[x>3,a] ]   -->   a
 Scope[{x:=2}, If[x>3,a] ]   -->   ()

 Scope[{x:=4}, If[x>3,a,b] ]   -->   a
 Scope[{x:=2}, If[x>3,a,b] ]   -->   b

 Scope[{x:=4}, x>3?a?b ]   -->   a
 Scope[{x:=2}, x>3?a?b ]   -->   b

 Scope[{x:=4}, x>3?a?x>1?b?c ]   -->   a
 Scope[{x:=2}, x>3?a?x>1?b?c ]   -->   b
 Scope[{x:=0}, x>3?a?x>1?b?c ]   -->   c

The functions 'Until' and 'While' repeat a procedure:

 Scope[{x:=0}, While[x<100,x+=17],x ]   -->   102
 Scope[{x:=0}, Until[x>100,x+=17],x ]   -->   102

The function 'Do' with operator symbol ';' collects multiple procedures into
one:

 Scope[{x:=0}, While[x<100,Do[x+=19,x-=2]],x ]   -->   102
 Scope[{x:=0}, While[x<100,   x+=19;x-=2 ],x ]   -->   102
 Scope[{x:=0}, While[x<100,   x+=19;x-=2 ];x ]   -->   102

The loop function 'For' repeats a procedure with loop variables:

 Scope[{x:=0}, For[x+=i     ,(=i,1:100=)          ],x ]   -->   5050
 Scope[{x:=0}, For[x+=i;x+=j,(=i,1:50,j,51:100=)  ],x ]   -->   5050
 Scope[{x:=0}, For[x+=i;x+=j,(=i,1:10=),(=j,1:10=)],x ]   -->   1100

 Scope[{x:=0}, For[x+=i     ,(=i,{a,b,c,d,e}=)    ],x ]   -->   a+b+c+d+e

 i   -->   i

Loop variables are managed by the loop function. They do not exist outside the
loop. Iterator expressions such as (=i,1:100=) define the loop variables and
their range, e.g. a variable i ranging from 1 to 100. Multiple variables in the
same iterator run in parallel. Loops with multiple iterators iterate over
multiple dimensions.

The loop function 'Table' lists the results of such iterations:

 Table[i  ,(=i,1:4=)          ]   -->   {1,2,3,4}
 Table[i:j,(=i,1:4,j,5:8=)    ]   -->   {1:5,2:6,3:7,4:8}
 Table[i:j,(=i,1:2=),(=j,1:3=)]   -->   {{1:1,1:2,1:3},{2:1,2:2,2:3}}

The function 'Break' exits the nearest enclosing loop.

 Table[i,(=i,1:7=)]   -->   {1,2,3,4,5,6,7}
 Table[i==4?Break;i,(=i,1:7=)]   -->   {1,2,3}

The function 'Continue' goes to the next step in the current loop.

 Table[i,(=i,1:5=)]   -->   {1,2,3,4,5}
 Table[i==3?Continue;i,(=i,1:5=)]   -->   {1,2,4,5}

The following table summarizes the flow control functions.

    Operator    Function    Usage
  --------------------------------------------------------------------------
    ?           If          If[test1,proc1,test2,proc2,test3,proc3,...]
                If1         If1[test,proc]
                If2         If2[test,proc1,proc2]
                Break
                Continue
    ;           Do          proc1; proc2; proc3; proc4; ...
                While       While[test,proc]
                Until       Until[test,proc]
    (= =)       Iterator    (=index1,range1,index2,range2,...=)
                For         For[proc,iterator1,iterator2,iterator3,...]
                Table       Table[proc,iterator1,iterator2,iterator3,...]
                Sum         Sum[proc,iterator1,iterator2,iterator3,...]
                Product     Product[proc,iterator1,iterator2,iterator3,...]

  'proc.' is a procedure to be evaluated under certain conditions.

  'range' specifies the range of a loop variable. It may have one of the
          following forms:

           start:stop
           start:stop:step
           {elem1,elem2,elem3,...}

For the moment, please have a look at the function list and the example
programs. This will be accomplished when I have time.


???. FUNCTIONAL PROGRAMMING
===========================

Functional programming typically solves a problem by evaluating one expression
and, recursivly, all of its subexpressions. As the interpreter must take care
to evaluate the subexpressions before the time they are needed, the order of
their evaluation is implicitly clear. A programmer must know the details of how
the interpreter evaluates functional expressions.

Here is a functional expression,

 Mul[Add[3,4],5]   -->   35

which one could equally well write with operators:

 (3+4)*5   -->   35

As we all expect, the addition of 3 and 4 must be evaluated before the
multiplication of its result by 5. The standard procedure is that the
interpreter first evaluates all the arguments from the left to the right,
i. e. first the Add[3,4] and then the 5. Their results are pushed on the stack.
Next, the interpreter evaluates the head Mul. Mul returns a pointer to the
built-in multiplication routine, which is then applied to the arguments on the
stack.

A head that evaluates to something other than a function - be it a built-in
function or an user-defined function - will simply be reused as a head in a new
expression:

 f[Add[3,4],5]   -->   f[7,5]
 (6+3)[Add[3,4],5]   -->   9[7,5]

In some cases, however, the standard order of evaluation would not produce the
desired results:

 If[3==3,Spell["yes\n"],Spell["no\n"]]   -->   ()
 If[3==4,Spell["yes\n"],Spell["no\n"]]   -->   ()

Spell is a function with a side efferct: it writes a string into an output
stream, but gives no result.

The first argument in the If[] expression is a test, depending on which
either the second or the third argument will be evaluated. The standard
procedure would evaluate both, which is not desired. Instead, the interpreter
must not evaluate any of the arguments in an If[]. This is in the
responsibility of the built-in If[] routine.

Okay - but how does the interpreter know when to evaluate an argument, and when
not? In TL this is controlled by evaluation masks. These are strings that may be
associated with a function definition. Masks can be checked with the command
'Mask':

 Mask[Let]   -->   "01"
 Mask[If]    -->   "{0}"
 Mask[If1]   -->   "00"
 Mask[If2]   -->   "000"
 Mask[Add]   -->   "{1}"
 Mask[Mask]  -->   "0"
 Mask[Dup]   -->   ~Void~

The digits correspond to the arguments, the first digit to the first argument,
the second digit to the second argument, and so on. An '1' means that the
argument is being evaluated according to the standard procedure, whereas a '0'
means that it remains unevaluated. Digits in '{}' match to a variable number of
arguments. Mask returns a void expression if no mask is defined. Functions
without a mask are treated according to the standard procedure, of course. The
evaluation mask is also a means to tell how many arguments a function expects.

Self-made functions can be provided with a mask using the command 'SetMask':

 f:=<<Dup,Length,Swap,'Add,Apply,Swap,Div>>   -->   ()
 SetMask[f,"1"]   -->   ()
 f[{1,2,2+1,4,5}]   -->   3
 Mask[f]   -->   "1"
 Forget[f]   -->   ()

In some cases, it is necessary to escape the evaluation mode prescribed by the
mask. Evaluation of an expression can be inhibited by wrapping it into the
'Hold' expression. 'Hold' has the operator ' .

 Hold[3+4]   -->   3+4
 '(3+4)   -->   3+4
 ''(3+4)   -->   '(3+4)

In other cases, one would like to evaluate a function argument whose mask digit
is '0': Wrap it into the 'Unhold' expression. 'Unhold' has the operator ` .

 `('{x,y}|2):=14   -->   ()
 x   -->   x
 y   -->   14
 Forget[y]   -->   ()

'Let' has the mask "01". The symbol that is its first argument is normally
prevented from being evaluated. We would otherwise get into problems if a symbol
had already been assigned a value. In our example above, however, we are
extracting the symbol 'y' from a list of symbols, which requires the extraction
to be evaluated. We do that extraction with the function 'Get', whose operator
is '|'.

The programmer can declare arguments explicitly in the function definition or
not. Please have a look at the following two versions of defining our averaging
function.

Here, the argument 'list' is explicitly declared:

 f[list]:=<<Scope[{sum,len},sum=list@Add,len=Length[list],sum/len]>>

Here, the list of numbers is implicitly assumed to be present on the stack:

 f:=<<Dup,Length,Swap,'Add,Apply,Swap,Div>>

Running the explicit version will store the list of numbers in the local
variable 'list' every time the function is called. The symbol 'list' must be
looked upevery time the data is needed, which involves searching the definition
list. But it is easier to understand. The implicit version, on the other hand,
operates directly on the expressions on the stack. It does not have to look up
its argument and is therefore more efficient.

A function can have two types of arguments: Positional arguments and named
arguments. Here is a function that returns a list of its arguments:

 f[x,y,z->4]:=<<{x,y,z}>>   -->   ()
 f[2,3]   -->   {2,3,4}
 f[2,3,z->5]   -->   {2,3,5}
 Forget[f]   -->   ()

The x and the y are positional arguments, because their name is determined by
their position in the function's argument list. The z is a named argument or
option with the default value 4. Options may be provided to a function after
the positional arguments. During execution, both positional and named arguments
are stored in local variables and can be accessed by evaluating their names.

An appropriate mask for this function would be "11.", where the dot stands for
an arbitrary number of options.

The '<< >>' is, by the way, the operator for the head 'Function'. Functions are
expressions like any other TL expression and have the form Function[ ... ].
Evaluation of a function returns the function itself, because its mask is "{0}".

There are two ways to run a function, i.e. to evaluate its contents one after
the other, from the left to the right. The first is to store it in a variable
and then evaluate the variable. We have already seen that. The second way is
using the command 'Exec'. See what happens:

 2,3,Add   -->   5
 2,3,<<Add>>   -->   2,3,<<Add>>
 2,3,<<Add>>,Exec   -->   5

Please note, that the evaluation of a TL expression may push more than one
result expression on the stack. Two more examples:

 <<2,3>>   -->   <<2,3>>
 <<2,3>>,Exec   -->   2,3

TL has functions that take other functions as arguments. Two of them are known
from other functional languages, namly 'Map' and 'Apply'. Their operators are
'#' and '@',respectively.

 Map[{1,2,3,4,5},<<Dup,Mul>>]   -->   {1,4,9,16,25}
 {1,2,3,4,5}#<<Dup,Mul>>   -->   {1,4,9,16,25}

 Apply[{1,2,3,4,5},<<Add>>]   -->   15
 {1,2,3,4,5}@<<Add>>   -->   15

'Map' applies the function to each content of a composed expression, whereas
'Apply' replaces the head of a composed expression by the function and evaluates
that.


???. RULE-BASED PROGRAMMING
===========================

Rule-based programming is possibly the programming style that is the most
intuitive to a molecular biologist: It is like a cocktail of enzymes acting on a
target molecule. Our target molecule is, of course, an expression, and our
enzyme cocktail is a list of rules.

Our enzyme or rule, respectively, is an expression of the form A->B, where A is
a pattern and B is a substitute expression. The '->' is the operator for the
head 'Rule'. Please do not confuse the rule operator '->' with our evaluation
symbol '-->', the latter of which is meta-language. Rules can be applied to a
target expression using 'Replace':

 Replace[4,{3->0,4->0,5->1,4->2}]   -->   0
 Replace[5,{3->0,4->0,5->1,4->2}]   -->   1
 Replace[6,{3->0,4->0,5->1,4->2}]   -->   6

'Replace' is expecting its target as its first argument, and a list of rules as
its second. The 'Replace' function is searching the list of rules from the left
to the right until it finds a rule whose pattern matches the target. If it finds
a matching rule the target is replaced by the rule's substitute expression.
Otherwise, the target expression is returned. If the target is mached by more
than one rule, the first matching rule is applied.

TL has four different functions to apply rules to a target and each has an
operator:

    Operator    Function
  ---------------------------------
    -|          Replace
    =|          Transform
    *|          ReplaceComponents
    ^|          ReplaceContents

As we have already seen, 'Replace' tries to replace the target as a whole.
'ReplaceComponents' applies the rules to each component of a composed target
expression, whereas 'ReplaceContents' applies the rules to each content, i.e.
to every component except for the head. 'Transform', finally, runs recursively
through a composed expession, from the tips towards the root, trying to replace
every subexpression that matches. See what happens:

 1[1,1[1],1] -| {1->2}   -->   1[1,1[1],1]
 1[1,1[1],1] =| {1->2}   -->   2[2,2[2],2]
 1[1,1[1],1] *| {1->2}   -->   2[2,1[1],2]
 1[1,1[1],1] ^| {1->2}   -->   1[2,1[1],2]

 1[1,1[1],1] =| {1[1]->2}   -->   1[1,2,1]
 1[1,1[1],1] *| {1[1]->2}   -->   1[1,2,1]
 1[1,1[1],1] ^| {1[1]->2}   -->   1[1,2,1]

Rather than providing a rule for any possible target, one usually prefers
patterns that match whole classes of different expressions. This is achieved by
the use of blanks. Blanks are symbols that start with an underscore '_'. They
match everything:

 3 -| {_->2}   -->   2
 4 -| {_->2}   -->   2

 {2,3} -| {{_a,_b}->{_a,_a,_a}}   -->   {2,2,2}
 {4,3} -| {{_a,_b}->{_a,_a,_a}}   -->   {4,4,4}

 {2,2} -| {{_,_}->1}   -->   1
 {2,3} -| {{_,_}->1}   -->   1
 {2,3} -| {{_a,_b}->1}   -->   1
 {2,3} -| {{_a,_a}->1}   -->   {2,3}

There are named blanks, which have more letters than just the underscore, and
there are unnamed blanks. Named blanks can be used in the substitute expression
where they will be expanded. If a named blank occurs multiple times in a pattern,
the pattern matches only if all the corresponding subexpressions are equal.

There are special blanks that match a sequence of expressions. These are symbols
that start with two underscores '__':

 {}-|{{__a}->{__a,__a}}   -->   {}
 {1}-|{{__a}->{__a,__a}}   -->   {1,1}
 {1,2}-|{{__a}->{__a,__a}}   -->   {1,2,1,2}
 {1,2,3}-|{{__a}->{__a,__a}}   -->   {1,2,3,1,2,3}

Sometimes, it is necessery to make the matching of a pattern dependent of a
condition. To do so, just wrap the rule into a 'Condition' and provide an
appropriate test:

 2-|{_a->1/?_a>2,_a->0}   -->   0
 3-|{_a->1/?_a>2,_a->0}   -->   1

The '/?' is the 'condition' operator. The first rule, which replaces anything
by 1 matches only if that anything is grater than 2. Otherwise, the second rule
applies, which replaces anything by 0.

TL has two types of rules: The 'Rule' that we have already seen, and the
'DelayedRule', which we have not yet seen and which has the operator '=>'. The
difference is that the substitute expression of a 'DelayedRule' is being
evaluated at the time when the 'DelayedRule' is applied:

 2-|{_a->_a+1}   -->   2+1
 2-|{_a=>_a+1}   -->   3

Finally, I should mention that a rule does not necessarily need to have exactly
one substitute expression. See what happens:

 {1,2,3}=|{2->()}   -->   {1,3}
 {1,2,3}=|{2->(7,8)}   -->   {1,7,8,3}

Rule-based transformations are a very powerful programming technique. A typical
application is algebraic simplification. Please note, that TREEFINDER is able
to do algebraic simplification:

 2*x+x   -->   3*x

To learn more about rule-based programming, please have a look at the source of
the 'Simplify' function, which is in the file 'Kernel/miscellaneous.tl'.


???. OPERATOR LIST
==================

The operators are listed by increasing precedence.

    Symbol      Function                Type
  ---------------------------------------------------
    [           ComposedOp              LIST
    ]           EndComposedOp           ENDLIST
    {           ListOp                  LIST
    }           EndListOp               ENDLIST
    <<          FunctionOp              LIST
    >>          EndFunctionOp           ENDLIST
    (           ParenthesesOp           LIST
    )           EndParenthesesOp        ENDLIST
    (=          IteratorOp              LIST
    =)          EndIteratorOp           ENDLIST
    ,           CommaOp                 FLATINFIX
    ;           DoOp                    FLATINFIX
    :=          LetOp                   INFIX
    =           SetOp                   INFIX
    +=          AddROp                  INFIX
    -=          SubROp                  INFIX
    *=          MulROp                  INFIX
    /=          DivROp                  INFIX
    /?          ConditionOp             INFIX
    =>          DelayedRuleOp           INFIX
    ->          RuleOp                  INFIX
    -|          ReplaceOp               INFIX
    =|          TransformOp             INFIX
    *|          ReplaceComponentsOp     INFIX
    ^|          ReplaceContentsOp       INFIX
    ?           IfOp                    FLATINFIX
    <>          JoinStringsOp           FLATINFIX
    :           ChainOp                 FLATINFIX
    ^^          XorOp                   FLATINFIX
    ||          OrOp                    FLATINFIX
    &&          AndOp                   FLATINFIX
    !           NotOp                   PREFIX
    ==          EqOp                    INFIX
    !=          NeOp                    INFIX
    <           LtOp                    INFIX
    >           GtOp                    INFIX
    <=          LeOp                    INFIX
    >=          GeOp                    INFIX
    +           AddOp                   FLATINFIX
    -           SubOp                   INFIX
    *           MulOp                   FLATINFIX
    /           DivOp                   INFIX
    -           NegOp                   PREFIX
    /           InvOp                   PREFIX
    ^           PowOp                   INFIX
    @           ApplyOp                 INFIX
    #           MapOp                   FLATINFIX
    |           GetOp                   INFIX
    `           UnholdOp                PREFIX
    '           HoldOp                  PREFIX


???. FUNCTION LIST
==================

The functions are listed in alphabetical order. The first line of each
description is showing the function name, which is followed in most cases by
the function's evaluation mask and sometimes by the corresponding operator
symbol.


--------------------------------------------------------------------------------
Abs   "1"

Abs[-8]   -->   8
Abs[8]   -->   8

--------------------------------------------------------------------------------
Acos   "1"

Numerical function.

--------------------------------------------------------------------------------
Acosh   "1"

Numerical function.

--------------------------------------------------------------------------------
Add   "{1}"   +

Addition.

Add[1,2,3]   -->   6
1+2+3   -->   6
a+2*a   -->   3*a

--------------------------------------------------------------------------------
Add2   "11"

Two-argument version of Add[].

--------------------------------------------------------------------------------
AddArrays   "{1}"


--------------------------------------------------------------------------------
AddR   "01"   +=

Same as Add[], but operates on a stored expression.

Scope[{x:=3},x+=1,x]   -->   4

--------------------------------------------------------------------------------
Alternate   "{1}"

Alternates one or more composed expressions of same length under the head of
the first.

Alternate[f[a,b],g[y,z]]   -->   f[a,y,b,z]
Alternate[{a,b,c},{d,e,f}]   -->   {a,d,b,e,c,f}

--------------------------------------------------------------------------------
And   "{1}"   &&

Logical AND.

True&&True   -->   True
And[True,False]   -->   False
False, True, And   -->   False

--------------------------------------------------------------------------------
Append   "11"

Appends a component.

Append[f[x,y],88]   -->   f[x,y,88]

--------------------------------------------------------------------------------
AppendR   "01"

Same as Append[], but operates on a stored expression.

Scope[{x:={a,b,c}},AppendR[x,f],x]   -->   {a,b,c,f}

--------------------------------------------------------------------------------
Apply   "10"   @

{3,4,5}@f   -->   f[3,4,5]
{3,4,5}@Add   -->   12

--------------------------------------------------------------------------------
AreTipCompatible   "11"


--------------------------------------------------------------------------------
ArrangeSequences   "11"


--------------------------------------------------------------------------------
Asin   "1"

Numerical function.

--------------------------------------------------------------------------------
Asinh   "1"

Numerical function.

--------------------------------------------------------------------------------
AsEdgeLengths   "1"

AsEdgeLengths[{{"a":0,"b":1}:-1,{"c":6,"d":7}:2}:-4]   -->   {{"a":1.,"b":2.}:3.,{"c":4.,"d":5.}:6.}

--------------------------------------------------------------------------------
AsNodeTimes   "11"

AsNodeTimes[{{"a":1,"b":2}:3,{"c":4,"d":5}:6},-4]   -->   {{"a":0.,"b":1.}:-1.,{"c":6.,"d":7.}:2.}:-4.

--------------------------------------------------------------------------------
AsReal   "1"

AsReal[245]   -->   245.0

--------------------------------------------------------------------------------
AsReport   "1"


--------------------------------------------------------------------------------
AsTree   "1"


--------------------------------------------------------------------------------
AsTreeList   "1"


--------------------------------------------------------------------------------
Atan   "1"

Numerical function.

--------------------------------------------------------------------------------
Atanh   "1"

Numerical function.

--------------------------------------------------------------------------------
Atol   "0{0}"

Atol[0.0001, 2.300==2.301 ]   -->   False
Atol[0.01,   2.300==2.301 ]   -->   True

--------------------------------------------------------------------------------
BaseComposition   "1."

BaseComposition[data] gives the normalized nucleotide frequencies.
BaseComposition[data,DataType->"AminoAcids"] gives amino acid frequencies.
BaseComposition[data,DataType->"Nucleotides"] gives nucleotide frequencies.

--------------------------------------------------------------------------------
BaseCounts   "1."

BaseCounts[data] gives the absolute nucleotide counts.
BaseCounts[data,DataType->"AminoAcids"] gives amino acid counts.
BaseCounts[data,DataType->"Nucleotides"] gives nucleotide counts.

--------------------------------------------------------------------------------
Beta   "11"

Numerical function.

--------------------------------------------------------------------------------
BetaP   "111"

Numerical function.

--------------------------------------------------------------------------------
BetaQ   "111"

Numerical function.

--------------------------------------------------------------------------------
BetaX   "111"

Numerical function.

--------------------------------------------------------------------------------
Binomial   "11"

Binomial[5,2] gives 10.

--------------------------------------------------------------------------------
BootstrapAnalysis   "1."


--------------------------------------------------------------------------------
Break   ""

Exits the nearest enclosing loop.

Table[i,(=i,1:7=)]   -->   {1,2,3,4,5,6,7}
Table[i==4?Break;i,(=i,1:7=)]   -->   {1,2,3}

--------------------------------------------------------------------------------
Build

a,b,c,d,e, f,Build   -->   f[a,b,c,d,e]
Build[5,6]   -->   6[5]

--------------------------------------------------------------------------------
BuildConsensusTree   "1."

Computes the consensus tree for a given list of trees.

 BuildConsensusTree[ _treelist_ , _options_ ]

   option            type       default
  ......................................
   Strict            BOOLEAN    FALSE
   WithEdgeLengths   BOOLEAN    TRUE
   WithEdgeSupport   BOOLEAN    TRUE

   parameter    form
  ..........................................................
   _treelist_   { _tree_ , _tree_ , _tree_ }
   _tree_       {"a":0.1,"b":0.2,{"c":0.1,"d":0.1}:0.1}


--------------------------------------------------------------------------------
BuildDistanceTree   "1."


--------------------------------------------------------------------------------
CalibrateTree   "11."


--------------------------------------------------------------------------------
Catch   "0"

Catch[expr] returns "" or the error message produced when evaluating expr.
Error messages can be generated by Throw[].

Catch[45+0]   -->   ""
Catch[45/0]   -->   "DivRaw: Division by zero."
Catch[Throw["My own error message."]]   -->   "My own error message."

--------------------------------------------------------------------------------
Cbrt   "1"

Numerical function.

--------------------------------------------------------------------------------
CDF   "11"

CDF[distribution,x] is the cumulative distribution function.
Distributions are the same as for Random[].

--------------------------------------------------------------------------------
Ceiling   "1"

Ceiling[x] gives the smallest integer greater than or equal to x.

Ceiling[2.1]   -->   3
Ceiling[2]   -->   2

--------------------------------------------------------------------------------
Chain   :

Represents a chain of expressions.

a,b,c,d,e, Chain   -->   a:b:c:d:e
Chain[www,3,4]   -->   www:3:4

--------------------------------------------------------------------------------
ChangeDirectory   "1"

ChangeDirectory["newdirectoryname"] changes the current directory.

--------------------------------------------------------------------------------
Characters   "1"

Characters["hello!"]   -->   {"h","e","l","l","o","!"}

--------------------------------------------------------------------------------
CheckBaseComposition   "1."


--------------------------------------------------------------------------------
CheckNameCompatibility   "11"


--------------------------------------------------------------------------------
Clear

Deletes the stack.

a,b,c,d,e, Clear   -->   ()

--------------------------------------------------------------------------------
Close   "1"

Close[file] closes a file stream.

--------------------------------------------------------------------------------
Collapse   "11"

Collapse[{"a":0.2,{"b":0.2,"c":0.2}:0.1,"d":0.2},0.15]   -->   {"a":0.2,"b":0.2,"c":0.2,"d":0.2}

--------------------------------------------------------------------------------
CollectPartitions   "1"


--------------------------------------------------------------------------------
Compress   "1"

Arithmetic data compression.

Compress["abcdeabcbcbceabcbcbcb"]   -->   "<`A[3B()bM|@O~~"
Uncompress["<`A[3B()bM|@O~~"]   -->   "abcdeabcbcbceabcbcbcb"

--------------------------------------------------------------------------------
ComputeSitewiseLikelihoods   "11."


--------------------------------------------------------------------------------
ComputeSitewiseRates   "11"


--------------------------------------------------------------------------------
CondenseLowerTriangle   "1"

CondenseLowerTriangle[{{0,-21,-31},{21,0,-32},{31,32,0}}]   -->   {21,31,32}

--------------------------------------------------------------------------------
CondenseSequences   "11."


--------------------------------------------------------------------------------
CondenseUpperTriangle   "1"

CondenseUpperTriangle[{{0,12,13},{-12,0,23},{-13,-23,0}}]   -->   {12,13,23}

--------------------------------------------------------------------------------
Condition   "10"   /?

"no" -|{_a->"yes"              }   -->   "yes"
"no" -|{_a->"yes"/?IsNumber[_a]}   -->   "no"
10   -|{_a->"yes"/?IsNumber[_a]}   -->   "yes"

--------------------------------------------------------------------------------
Continue   ""

Goes to the next step in the current loop.

Table[i,(=i,1:5=)]   -->   {1,2,3,4,5}
Table[i==3?Continue;i,(=i,1:5=)]   -->   {1,2,4,5}

--------------------------------------------------------------------------------
CopyFile   "11"

CopyFile["from","to"] copies a file.

--------------------------------------------------------------------------------
Cos   "1"

Numerical function.

--------------------------------------------------------------------------------
Cosh   "1"

Numerical function.

--------------------------------------------------------------------------------
Cot   "1"

Numerical function.

--------------------------------------------------------------------------------
CountTopologies   "1"


--------------------------------------------------------------------------------
Create   "0"

Creates a new variable without assigning a value.

--------------------------------------------------------------------------------
Cut   "11"

Cut[{g,a,n,g,o,l,f},{3,5}]   -->   {n,g,o}
Cut[{g,a,n,g,o,l,f},{5,3}]   -->   {o,g,n}
Cut[{g,a,n,g,o,l,f},{3,5,3,5}]   -->   {n,g,o,n,g,o}

--------------------------------------------------------------------------------
CutSequences   "11"

Cuts columns out of a sequence alignment analogously to Cut[].

--------------------------------------------------------------------------------
CutString   "11"

CutString["gangolf",{3,5}]   -->   "ngo"
CutString["gangolf",{5,3}]   -->   "ogn"
CutString["gangolf",{3,5,3,5}]   -->   "ngongo"

--------------------------------------------------------------------------------
Def   "{1}0"

Same as let, but with reversed arguments.

--------------------------------------------------------------------------------
Defargs


--------------------------------------------------------------------------------
DelayedRule   "0{0}"   =>

Represents a rule that is evaluated at replacement time.

Rule[x,3+4]   -->   x->7
DelayedRule[y,3+4]   -->   y=>3+4
f[x,y]=|{x->3+4,y=>3+4}   -->   f[3+4,7]
f[x,y]=|`{x->3+4,y=>3+4}   -->   f[7,7]

--------------------------------------------------------------------------------
Dimensions   "1"

Dimensions[{{2,a},{q,5}}]   -->   {2,2}

--------------------------------------------------------------------------------
Directory   ""


--------------------------------------------------------------------------------
Dissimilarity   "11"

Returns the dissimilarity between two tree topologies.

--------------------------------------------------------------------------------
Div   "11"   /

Division.

Div[12,3]   -->   4
12/3   -->   4

--------------------------------------------------------------------------------
DivR   "01"   /=

Same as Div[], but operates on a stored expression.

Scope[{x:=6},x/=2,x]   -->   3

--------------------------------------------------------------------------------
Do   "{0}"   ;

Collects multiple procedures into one.

Do[5,2,Add]   -->   7
5;2;Add   -->   7

Scope[{x:=0}, While[x<100,Do[x+=19,x-=2]],x ]   -->   102
Scope[{x:=0}, While[x<100,   x+=19;x-=2 ],x ]   -->   102

--------------------------------------------------------------------------------
Dot   "11"

Dot[{a,b,c},{d,e,f}]   -->   a*d+b*e+c*f
Dot[{a,b,c},{{d,e,f},{g,h,i},{j,k,l}}]   -->   {a*d+b*g+c*j,a*e+b*h+c*k,a*f+b*i+c*l}
Dot[{{a,b,c},{d,e,f},{g,h,i}},{j,k,l}]   -->   {a*j+b*k+c*l,d*j+e*k+f*l,g*j+h*k+i*l}

--------------------------------------------------------------------------------
Drop

Removes the topmost expression from stack.

a,b,c,d,e, Drop   -->   a,b,c,d

--------------------------------------------------------------------------------
Dup

Duplicates the topmost expression on stack.

a,b,c,d,e, Dup   -->   a,b,c,d,e,e

--------------------------------------------------------------------------------
DupN

a,b,c,d,e, 3,DupN   -->   a,b,c,d,e,c,d,e

--------------------------------------------------------------------------------
Edit   "1."


--------------------------------------------------------------------------------
EditLines   "1"


--------------------------------------------------------------------------------
EditList   "1."


--------------------------------------------------------------------------------
Environment   "1"


--------------------------------------------------------------------------------
Eq   "11"   ==

Equal.

1==2   -->   False
2==2.   -->   True
2.,2.1, Eq   -->   False
{a,b,{c}},{a,b,{c}}, Eq   -->   True
{a,b,{c}}=={a,b,{_}}   -->   True
Rtol[0.01,2300.==2301.]   -->   True

--------------------------------------------------------------------------------
Erf   "1"

Numerical function.

--------------------------------------------------------------------------------
Erfc   "1"

Numerical function.

--------------------------------------------------------------------------------
Eval   "0"


--------------------------------------------------------------------------------
ExcludeDistances   "11"


--------------------------------------------------------------------------------
ExcludePartitions   "11"


--------------------------------------------------------------------------------
ExcludeSequences   "11"


--------------------------------------------------------------------------------
Exec   "0"


--------------------------------------------------------------------------------
Exenv   "00"


--------------------------------------------------------------------------------
Exp   "1"

Exponential function.

--------------------------------------------------------------------------------
ExpandLowerTriangle   "1"

ExpandLowerTriangle[{21,31,32}]   -->   {{0,21,31},{21,0,32},{31,32,0}}

--------------------------------------------------------------------------------
ExpandUpperTriangle   "1"

ExpandUpperTriangle[{12,13,23}]   -->   {{0,12,13},{12,0,23},{13,23,0}}

--------------------------------------------------------------------------------
Extend   "111"

Extend[u[2,3],,1]   -->   u[2]
Extend[u[2,3],,4]   -->   u[2,3,,]
Extend[u[2,3],a,6]   -->   u[2,3,a,a,a,a]

--------------------------------------------------------------------------------
Extrovert   "1"

Extrovert[{{a,b,c},{d,e,f}}]   -->   {{a,d},{b,e},{c,f}}
Extrovert[{{{a,b,c},{d,e,f}}}]   -->   {{{a,d}},{{b,e}},{{c,f}}}  )
Extrovert[{{{a},{b}},{{c},{d}},{{e},{f}}}]   -->   {{{a,b},{c,d},{e,f}}}  )

--------------------------------------------------------------------------------
Factorial   "1"


--------------------------------------------------------------------------------
FilePosition   "1"


--------------------------------------------------------------------------------
FileSeparator   ""


--------------------------------------------------------------------------------
Flatten   "1"

Flatten[{a,{b,c},d}]   -->   {a,b,c,d}
Flatten[{a,{},{b[w,{r,s}]},c}]   -->   {a,b[w,{r,s}],c}

--------------------------------------------------------------------------------
Floor   "1"

Floor[x] gives the greatest integer less than or equal to x.

Floor[-0.3]   -->   -1

--------------------------------------------------------------------------------
For   "00{0}"

For[f,(=i,...=)] evaluates f with loop variables i,... .

Scope[{x:=0}, For[x+=i     ,(=i,1:100=)          ],x ]   -->   5050
Scope[{x:=0}, For[x+=i;x+=j,(=i,1:50,j,51:100=)  ],x ]   -->   5050
Scope[{x:=0}, For[x+=i;x+=j,(=i,1:10=),(=j,1:10=)],x ]   -->   1100

Scope[{x:=0}, For[x+=i     ,(=i,{a,b,c,d,e}=)    ],x ]   -->   a+b+c+d+e

--------------------------------------------------------------------------------
Forget   "0"


--------------------------------------------------------------------------------
Frequencies   "1"

Counts the contents of a composed expression.

Frequencies[{a,g,t,d,a,t,n,g,a,a,t,d,g,g}]   -->   {{a,4},{g,4},{t,3},{d,2},{n,1}}

--------------------------------------------------------------------------------
Function   "{0}"   << >>

Represents a function that can be executed.

Function[Add,2,Mul][2,3,4]   -->   18
<<Add,2,Mul>>[2,3,4]   -->   18

--------------------------------------------------------------------------------
FunctionTable   "1"


--------------------------------------------------------------------------------
Gamma   "1"

Gamma[x] is the Euler gamma function.

--------------------------------------------------------------------------------
GammaP   "11"

Numerical function.

--------------------------------------------------------------------------------
GammaQ   "11"

Numerical function.

--------------------------------------------------------------------------------
GammaY   "11"

Numerical function.

--------------------------------------------------------------------------------
Gc   ""

Frees memory that is currently not used by the TREEFINDER kernel.

--------------------------------------------------------------------------------
Ge   "11"   >=

Greater or equal.

4.7>=3   -->   True
1>=2   -->   False
Ge[1,2]   -->   False
4.0, 4 ,Ge   -->   True
"b", "a", Ge   -->   True

--------------------------------------------------------------------------------
GenerateSequences   "111."

GenerateSequences[ _tree_ , _model_ , _length_ , _options_ ] generates a
nucleotide or amino acid matrix according to a specified tree and evolution
model. _tree_ must have edge lengths.

 Options:

   option                 type       default
  ...........................................
   InsertionRate          REAL       0.
   InsertionLength        INTEGER    0


 Special expressions used in the options:

   parameter    form
  ..........................................................
   _tree_       {"a":0.1,"b":0.2,{"c":0.1,"d":0.1}:0.1}
   _model_      see program manual "Model Expressions"
   _length_     1200


--------------------------------------------------------------------------------
GenerateStartTrees   "1."


--------------------------------------------------------------------------------
Get   "11"   |

f[x,y,z[1,2]]|2   -->   y
Get[f[x,y,z[1,2]],{0}]   -->   f
Get[f[x,y,z[1,2]],{3,2}]   -->   2
Get[{a,b,c,d,e},4]   -->   d
Get[{a,b,c,d,e},-2]   -->   d

--------------------------------------------------------------------------------
GetR   "01"

Same as Get[], but operates on a stored expression.

Scope[{x:={a,b,c}},GetR[x,2]]   -->   b

--------------------------------------------------------------------------------
GetAlignmentLength   "1"


--------------------------------------------------------------------------------
Getargs


--------------------------------------------------------------------------------
GetEdgeLengths   "1"


--------------------------------------------------------------------------------
GetEdgeSupport   "1"


--------------------------------------------------------------------------------
GetFilterNames   "1"


--------------------------------------------------------------------------------
GetFilters   "1"


--------------------------------------------------------------------------------
GetNumbers   "1"

GetNumbers[f[4.,a,{5.,6.}]]   -->   {4.,5.,6.}

--------------------------------------------------------------------------------
GetPartitionKeys   "1"


--------------------------------------------------------------------------------
GetPartitionLengths   "1"


--------------------------------------------------------------------------------
GetSequenceChecksum   "1"


--------------------------------------------------------------------------------
GetSequenceLengths   "1"


--------------------------------------------------------------------------------
GetSequenceNames   "1"


--------------------------------------------------------------------------------
GetTipNames   "1"

GetTipNames[{"b",{"a","f"},{"j","s"}}]   -->   {"b","a","f","j","s"}

--------------------------------------------------------------------------------
GetTree   "11"


--------------------------------------------------------------------------------
Group   "11"

Group[{a,s,d,f,g,h,j},2]   -->   {{a,s},{d,f},{g,h},{j}}
Group[f[d,a,e,b,f,c],2]   -->   f[{d,a},{e,b},{f,c}]

--------------------------------------------------------------------------------
Gt   "11"   >

Greater than.

4.7>3   -->   True
1>2   -->   False
Gt[1,2]   -->   False
4.0, 4 ,Gt   -->   False
"ab", "aa" ,Gt   -->   True

--------------------------------------------------------------------------------
HandleAlgebraicExpressions


--------------------------------------------------------------------------------
HasFilters   "1"


--------------------------------------------------------------------------------
Head   "1"

Head[f[x,y]]   -->   f

--------------------------------------------------------------------------------
Hold

Prevents an expression from being evaluated.

3+4   -->   7
'(3+4)   -->   3+4
''(3+4)   -->   '(3+4)

--------------------------------------------------------------------------------
Hyp2f1   "1111"

Numerical function.

--------------------------------------------------------------------------------
Idiv   "11"

Integer Division.

Idiv[13,2]   -->   6

--------------------------------------------------------------------------------
Ierf   "1"

Numerical function.

--------------------------------------------------------------------------------
If   "{0}"   ?

If2[~test1~,~proc1~,~test2~,~proc2~,...,~procN~] evaluates ~proc1~ if test1
gives True. Otherwise, ~test2~ is tried and, if that gives True, ~proc2~ is
evaluated and so on. If no test gives True, ~procN~ is evaluated if present.
Takes all expressions from the stack from the stack.

If[2<3,"this"]   -->   "this"
If[2>3,"this"]   -->   ()
If[2<3,"this","that"]   -->   "this"
If[2>3,"this","that"]   -->   "that"
If[2>3,"this",2>5,"that","muhu"]   -->   "muhu"
2>3?"this"?2>5?"that"?"muhu"   -->   "muhu"
If[2>3,"this",2>5,"that"]   -->   ()

--------------------------------------------------------------------------------
If1   "00"

If1[~test~,~proc~] evaluates ~proc~ if ~test~ gives True.
Takes 2 expressions from the stack.

If1[2<3,"this"]   -->   "this"
If1[2>3,"this"]   -->   ()
2<3,"this",If1   -->   "this"
2>3,"this",If1   -->   ()

--------------------------------------------------------------------------------
If2   "000"

If2[~test~,~proc1~,~proc2~] evaluates ~proc1~ if ~test~ gives True. Otherwise,
~proc2~ is evaluated. Takes 3 expressions from the stack.

If2[2<3,"this","that"]   -->   "this"
If2[2>3,"this","that"]   -->   "that"
2<3,"this","that",If2   -->   "this"
2>3,"this","that",If2   -->   "that"

--------------------------------------------------------------------------------
IncludeCodonFilter   "111"


--------------------------------------------------------------------------------
IncludeFilters   "1111"


--------------------------------------------------------------------------------
IncludeRateFilter   "1111"


--------------------------------------------------------------------------------
InitRandom   "1"


--------------------------------------------------------------------------------
InnerDimension   "1"

InnerDimension[{a,b,c,d}]   -->   4
InnerDimension[{a,b,{c,d}}]   -->   3
InnerDimension[{{a,b},{c,d}}]   -->   2

--------------------------------------------------------------------------------
Input   "1"


--------------------------------------------------------------------------------
Insert   "111"

Insert[f[x,y,z[1,2]],{2},88]   -->   f[x,88,y,z[1,2]]
Insert[f[x,y,z[1,2]],{3,3},88]   -->   f[x,y,z[1,2,88]]

--------------------------------------------------------------------------------
InsertR   "011"

Same as Insert[], but operates on a stored expression.

Scope[{x:={a,b,c}},InsertR[x,2,f],x]   -->   {a,b,f,c}

--------------------------------------------------------------------------------
Interpolate   "11"


--------------------------------------------------------------------------------
InterpolateDerivative   "11"


--------------------------------------------------------------------------------
InterpolateIntegral   "111"


--------------------------------------------------------------------------------
Interpret   "1."

Interpret["3,4,Add"]   -->   7

--------------------------------------------------------------------------------
Introvert   "1"

Introvert[{{a,b,c},{d,e,f}}]   -->   {{a,d},{b,e},{c,f}}
Introvert[{{{a,b,c},{d,e,f}}}]   -->   {{{a},{b},{c}},{{d},{e},{f}}}  )
Introvert[{{{a},{b}},{{c},{d}},{{e},{f}}}]   -->   {{{a,c,e}},{{b,d,f}}}  )

--------------------------------------------------------------------------------
Inv   "1"

Inv[4.]   -->   0.25

--------------------------------------------------------------------------------
InverseTable   "1"


--------------------------------------------------------------------------------
Iphi   "1"

Numerical function.

--------------------------------------------------------------------------------
IsBoolean   "1"

IsBoolean[False]   -->   True
IsBoolean[4.]   -->   False

--------------------------------------------------------------------------------
IsBranchSpecifier   "1"


--------------------------------------------------------------------------------
IsCalibrationData   "1"

IsCalibrationData["o"["b","c"]["a":-0.36,{"b","a"}:-0.43]]   -->   True

--------------------------------------------------------------------------------
IsChain   "1"

IsChain[x]   -->   False
IsChain[1:2:3]   -->   True
IsChain[{1,2,3}]   -->   False

--------------------------------------------------------------------------------
IsCluster   "11"


--------------------------------------------------------------------------------
IsCompatibleCluster   "11"


--------------------------------------------------------------------------------
IsCompatibleTree   "11"


--------------------------------------------------------------------------------
IsComposed   "1"

IsComposed[x]   -->   False
IsComposed[{1,2,3}]   -->   True
IsComposed[f[1,2,3]]   -->   True

--------------------------------------------------------------------------------
IsDigit   "1"

IsDigit["4"]   -->   True
IsDigit["67"]   -->   False
IsDigit["u"]   -->   False

--------------------------------------------------------------------------------
IsDistances   "1"

IsDistances[{{"uhu","gnu","baer"},{3.3,5.7,8.2}}]   -->   True

--------------------------------------------------------------------------------
IsFunction   "1"

IsFunction[<<7,8>>]   -->   True
IsFunction[u]   -->   False

--------------------------------------------------------------------------------
IsInteger   "1"

IsInteger[73]   -->   True

--------------------------------------------------------------------------------
IsInvariable   "1"

IsInvariable[{2,2,2,2,2}]   -->   True
IsInvariable[{4,5,4}]   -->   False

--------------------------------------------------------------------------------
IsLetter   "1"

IsLetter["h"]   -->   True
IsLetter["df"]   -->   False
IsLetter["7"]   -->   False

--------------------------------------------------------------------------------
IsList   "1"

IsList[{1,2,3}]   -->   True
IsList[f[1,2,3]]   -->   False
IsList[x]   -->   False

--------------------------------------------------------------------------------
IsLocal   "0"

IsLocal[i]   -->   False
Table[IsLocal[i],(=i,1:2=)]   -->   {True,True}
Scope[{i},IsLocal[i]]   -->   True
IsLocal[Add]   -->   False

--------------------------------------------------------------------------------
IsLocked   "0"

IsLocked[i]   -->   False
IsLocked[Add]   -->   False      (* because Add is redefined *)
IsLocked[StringLength]   -->   True
Table[IsLocked[i],(=i,1:2=)]   -->   {False,False}
Scope[{i},IsLocked[i]]   -->   False

--------------------------------------------------------------------------------
IsMatrix   "1"

IsMatrix[{{2,a},{q,5}}]   -->   True

--------------------------------------------------------------------------------
IsMember   "11"

IsMember[f[a,b,c],c]   -->   True
IsMember[{a,b,c},z]   -->   False

--------------------------------------------------------------------------------
IsNumber   "1"

IsInteger[73]   -->   True
IsInteger[73.0]   -->   True

--------------------------------------------------------------------------------
IsNumericMatrix   "1"


--------------------------------------------------------------------------------
IsNumericSquareMatrix   "1"


--------------------------------------------------------------------------------
IsNumericVector   "1"


--------------------------------------------------------------------------------
IsolateBranch   "11"


--------------------------------------------------------------------------------
IsolateFirstBranch   "1"


--------------------------------------------------------------------------------
IsProtected   "0"

IsProtected[i]   -->   False
IsProtected[Add]   -->   True
IsProtected[StringLength]   -->   True
Table[IsProtected[i],(=i,1:2=)]   -->   {False,False}
Scope[{i},IsProtected[i]]   -->   False

--------------------------------------------------------------------------------
IsReal   "1"

IsInteger[73]   -->   False
IsInteger[73.0]   -->   True

--------------------------------------------------------------------------------
IsRealArray   "1"


--------------------------------------------------------------------------------
IsReport   "1."


--------------------------------------------------------------------------------
IsRoutine   "1"

IsRoutine[Lookup[IsRoutine]]   -->   True

--------------------------------------------------------------------------------
IsSequences   "1."

IsSequences[{"a":"TCC","b":"TTG","c":"TGT","d":"CCC","e":"CGC"}]   -->   True
IsSequences[{"a":"TCC","b":"TTG","c":"TGT","d":"G","e":"CGC"}]   -->   False
IsSequences[{"a":"TCC","b":"TTG","c":"TGT","d":"G","e":"CGC"},AcceptUnaligned->True]   -->   True

--------------------------------------------------------------------------------
IsSquareMatrix   "1"

IsSquareMatrix[{{2,a},{q,5}}]   -->   True

--------------------------------------------------------------------------------
IsStream   "1"


--------------------------------------------------------------------------------
IsString   "1"

IsString["bla 73"]   -->   True

--------------------------------------------------------------------------------
IsSubstitutionModel   "1."

IsSubstitutionModel[WAG[,]:G[{0.43}]]   -->   True
IsSubstitutionModel[HKY[Optimum,Empirical],WithParameters->True]   -->   False

--------------------------------------------------------------------------------
IsSymbol   "1"

IsSymbol[xy]   -->   True

--------------------------------------------------------------------------------
IsTree   "1."

IsTree[{"b",{"a","f"},"j"}]   -->   True
IsTree[{"b",{"a","f"},"j"},WithEdgeLengths->True]   -->   False

--------------------------------------------------------------------------------
IsTreeList   "1."


--------------------------------------------------------------------------------
IsVector   "1"

IsVector[{6,3.4,5}]   -->   True

--------------------------------------------------------------------------------
IsVoid   "1"

IsVoid[~Void~]   -->   True
IsVoid[{1,,3}|2]   -->   True

--------------------------------------------------------------------------------
Iterator   "{01}"   (= =)

Table[i,(=i,3:6=)]   -->   {3,4,5,6}

--------------------------------------------------------------------------------
Join   "{1}"

Concatenates one or more composed expressions under the head of the first.

Join[f[x],g[y,z]]   -->   f[x,y,z]
Join[{a,b},{},{c,d,e}]   -->   {a,b,c,d,e}

--------------------------------------------------------------------------------
JoinCodonPositions   "111"


--------------------------------------------------------------------------------
JoinReports   "{1}."

Concatenates two or more reconstruction reports.

--------------------------------------------------------------------------------
JoinSequences   "{1}."

Concatenates two or more sequence alignments.

--------------------------------------------------------------------------------
JoinStrings   "{1}"

Concatenates two or more strings. Expressions other than strings will be
converted to strings.

JoinStrings["abc","defg"]   -->   "abcdefg"

--------------------------------------------------------------------------------
JoinTrees   "{1}."

Concatenates two or more trees or tree lists into one comprehensive tree list.

--------------------------------------------------------------------------------
Ld   "1"

Logarithm to the base of 10.

--------------------------------------------------------------------------------
Le   "11"   <=

Less or equal.

1<=2   -->   True
Le[1,2]   -->   True
4.7, 3, Le   -->   False
4.0, 4, Le   -->   True

--------------------------------------------------------------------------------
Length   "1"

Length[{a,b,c}]   -->   3

--------------------------------------------------------------------------------
Let   "01"

Defines a new variable and assigns a value to it.

--------------------------------------------------------------------------------
List   { }

Represents a list of expressions.

a,b,c,d,e, List   -->   {a,b,c,d,e}
List[www,3,bb,4]   -->   {www,3,bb,4}

--------------------------------------------------------------------------------
ListN

a,b,c,d,e, 3,ListN   -->   a,b,{c,d,e}

--------------------------------------------------------------------------------
Ln   "1"

Natural logarithm.

--------------------------------------------------------------------------------
LnBeta   "11"

Numerical function.

--------------------------------------------------------------------------------
LnGamma   "1"

Numerical function.

--------------------------------------------------------------------------------
Load   "1."

Load["filename"] loads and runs a TL program.

--------------------------------------------------------------------------------
LoadCalibrationData   "1"


--------------------------------------------------------------------------------
LoadDistances   "1"


--------------------------------------------------------------------------------
LoadReport   "1."


--------------------------------------------------------------------------------
LoadSequences   "1."


--------------------------------------------------------------------------------
LoadText   "1"


--------------------------------------------------------------------------------
LoadTree   "1."


--------------------------------------------------------------------------------
LoadTreeList   "1."


--------------------------------------------------------------------------------
Log   "11"

Log[b,x] gives the logarithm of x to the base b.

--------------------------------------------------------------------------------
Lookup   "0"

Gets a function's definition.

Lookup[Mean]   -->   <<Dup,Length,Swap,'Add,Apply,Swap,Div>>

--------------------------------------------------------------------------------
Lt   "11"   <

Less than.

1<2   -->   True
Lt[1,2]   -->   True
4.7, 3 ,Lt   -->   False
4.0 ,4, Lt   -->   False

--------------------------------------------------------------------------------
MakeDirectory   "1"


--------------------------------------------------------------------------------
Map   "1{1}0"   #

{3,4,5}#f   -->   {f[3],f[4],f[5]}
{3,4,5}#{6,7,8}#f   -->   {f[3,6],f[4,7],f[5,8]}
{3,4,5}#Neg   -->   {-3,-4,-5}
Map[{3,6},f]   -->   {f[3],f[6]}
Map[{1,2},{3,6},f]   -->   {f[1,3],f[2,6]}
Map[x[1,2],y[3,6],f]   -->   x[f[1,3],f[2,6]]
Map[x[1,2],y[3,6],Add]   -->   x[4,8]

--------------------------------------------------------------------------------
Map1   "10"

Two-argument version of Map[].

--------------------------------------------------------------------------------
MapAt   "101"

MapAt[{3,4,5},Neg,2]   -->   {3,-4,5}
MapAt[{3,{4},5},Neg,{2,1}]   -->   {3,{-4},5}
MapAt[f[1,2,3,4],Neg,-2]   -->   f[1,2,-3,4]

--------------------------------------------------------------------------------
Mask   "0"

Gets a function's mask.

Mask[Mask]   -->   "0"

--------------------------------------------------------------------------------
Maskargs   "01"

Maskargs[f[x,y,z],"010"]   -->   f['x,y,'z]
Maskargs[f[x,y,x,y],"{01}"]   -->   f['x,y,'x,y]
Maskargs[f[x,a->b],"0{1}"]   -->   f['x,a->b]

--------------------------------------------------------------------------------
Max   "1"

Max[{1,3,2}]   -->   3

--------------------------------------------------------------------------------
Mean   "1"

Mean[{5,7,9,7,5,7,9,7}]   -->   7.

--------------------------------------------------------------------------------
Median   "1"


--------------------------------------------------------------------------------
Members   "1"

Members[{2,5,3,4,3,1,4,2,3}]   -->   {1,2,3,4,5}
Members[{a,g,t,d,a,t,n,g,a,a,t,d,g,g}]   -->   {a,g,t,d,n}

--------------------------------------------------------------------------------
MemoryInUse   ""

Returns the amount of memory in bytes that is currently allocated by the
TREEFINDER kernel.

--------------------------------------------------------------------------------
Merge   "1"

Merge[f[good[1,2],bad[6,8],good[9]]]   -->   f[good[1,2,9],bad[6,8]]

--------------------------------------------------------------------------------
Midroot   "1"


--------------------------------------------------------------------------------
Min   "1"

Min[{1,3,2}]   -->   1

--------------------------------------------------------------------------------
Mod   "11"

Mod[13,5]   -->   3

--------------------------------------------------------------------------------
MoveFile   "11"

MoveFile["from","to"] moves a file.

--------------------------------------------------------------------------------
Mul   "{1}"   *

Multiplication.

Mul[1,2,3]   -->   6
1*2*3   -->   6

--------------------------------------------------------------------------------
Mul2   "11"

Two-argument version of Mul[].

--------------------------------------------------------------------------------
MulArrays   "{1}"


--------------------------------------------------------------------------------
MulR   "01"   *=

Same as Mul[], but operates on a stored expression.

Scope[{x:=3},x*=2,x]   -->   6

--------------------------------------------------------------------------------
NBranches   "1"

NBranches[{{"A","B"},{"C","D"},{"E","F"}}]   -->   9

--------------------------------------------------------------------------------
Ne   "11"   !=

Not equal.

1!=2   -->   True
100!=100   -->   False
100,112,  Ne   -->   True

--------------------------------------------------------------------------------
NEdges   "1"

NEdges[{"a","b",{"c","d"},"e"}]   -->   6

--------------------------------------------------------------------------------
Neg   "1"   -

Neg[8]   -->   -8
Neg[-8]   -->   8

--------------------------------------------------------------------------------
NodeSize   ""


--------------------------------------------------------------------------------
NOpenFiles   ""


--------------------------------------------------------------------------------
Not   "1"   !

Logical NOT.

!True   -->   False
Not[False]   -->   True
True, Not   -->   False

--------------------------------------------------------------------------------
NTips   "1"

NTips[{{"A","B","X"},{"C","D"},"E"}]   -->   6

--------------------------------------------------------------------------------
Objects   ""

Returns a list of the currently defined objects.

--------------------------------------------------------------------------------
Open   "11"

Open["filename",_mode_] opens and returns a file stream.
The file named   "filename" can be opened for reading (_mode_ = "r"),
writing (_mode_ = "r"), or appending (_mode_ = "a") ASCII text.

--------------------------------------------------------------------------------
OpenFiles   ""

Returns the number of open files.

--------------------------------------------------------------------------------
Oprec   "0{0}"

Set temporarily the output precision for real numbers. Affects Write[]
and ToString[].

Oprec[5,ToString[Pi]]   -->   "3.1416"
Oprec[3,ToString[Pi]]   -->   "3.14"

--------------------------------------------------------------------------------
Or   "{1}"   ||

Logical OR.

True||False   -->   True
Or[False,False]   -->   False
False, True ,Or   -->   True

--------------------------------------------------------------------------------
PadLeft   "11"

PadLeft[str,n] makes a string of length n by padding str with whitespace on
the left. Expressions other than strings will be converted to strings.

PadLeft["",9]   -->   "         "
PadLeft["gaguff",9]   -->   "   gaguff"
PadLeft["gaguff",4]   -->   "guff"
PadLeft[16,5]   -->   "   16"

--------------------------------------------------------------------------------
PadRight   "11"

PadRight[str,n] makes a string of length n by padding str with whitespace on
the right. Expressions other than strings will be converted to strings.

PadRight["",9]   -->   "         "
PadRight["gaguff",9]   -->   "gaguff   "
PadRight["gaguff",4]   -->   "gagu"

--------------------------------------------------------------------------------
PairedSitesTests   "1."


--------------------------------------------------------------------------------
Parentheses   "{1}"


--------------------------------------------------------------------------------
PDF   "11"

PDF[distribution,x] is the probability density function.
Distributions are the same as for Random[].

--------------------------------------------------------------------------------
Permute   "11"

Permute[{a,b,c,d,e,f},{3,5,1,2,6,4}]   -->   {c,e,a,b,f,d}

--------------------------------------------------------------------------------
PermuteColumns   "11"

PermuteColumns[{{a,b,c,d,e,f},{q,r,s,t,u,v}},{3,5,1,2,6,4}]   -->   {{c,e,a,b,f,d},{s,u,q,r,v,t}}

--------------------------------------------------------------------------------
PermuteLevels   "11"

PermuteLevels[{{{a,b,x},{c,d,y}}},{1,3,2}]   -->   {{{a,c},{b,d},{x,y}}}
PermuteLevels[{{{a,b,x},{c,d,y}}},{2,1,3}]   -->   {{{a,b,x}},{{c,d,y}}}
PermuteLevels[{{{a,b,x},{c,d,y}}},{3,1,2}]   -->   {{{a},{b},{x}},{{c},{d},{y}}}

--------------------------------------------------------------------------------
PermuteMatrix   "11"

PermuteMatrix[{{a,b,c,d},{e,f,g,h},{i,j,k,l},{m,n,o,p}},{3,1,4,2}]   -->   {{k,i,l,j},{c,a,d,b},{o,m,p,n},{g,e,h,f}}

--------------------------------------------------------------------------------
Phi   "1"

Numerical function.

--------------------------------------------------------------------------------
Pick

a,b,c,d,e, 4,Pick   -->   a,b,c,d,e, b

--------------------------------------------------------------------------------
PlotPoints   "1."


--------------------------------------------------------------------------------
PlotTree   "1."


--------------------------------------------------------------------------------
PlotValues   "1."


--------------------------------------------------------------------------------
Pow   "11"   ^

2^3   -->   8

--------------------------------------------------------------------------------
Prepend   "11"

Prepend[f[x,y],88]   -->   f[88,x,y]

--------------------------------------------------------------------------------
PrependR   "01"

Same as Prepend[], but operates on a stored expression.

Scope[{x:={a,b,c}},PrependR[x,f],x]   -->   {f,a,b,c}

--------------------------------------------------------------------------------
Product   "00{0}"

Roughly equivalent to Table[...]@Mul .

Product[i,(=i,1:4=)]   -->   24

--------------------------------------------------------------------------------
ProfileMutations   "1"


--------------------------------------------------------------------------------
ProposeModel   "1."


--------------------------------------------------------------------------------
Protect   "0"


--------------------------------------------------------------------------------
Psi   "1"

Numerical function.

--------------------------------------------------------------------------------
Put   "111"

Put[f[x,y,z[1,2]],{2},88]   -->   f[x,88,z[1,2]]
Put[f[x,y,z[1,2]],{0},88]   -->   88[x,y,z[1,2]]
Put[f[x,y,z[1,2]],{3,2},88]   -->   f[x,y,z[1,88]]

--------------------------------------------------------------------------------
PutR   "011"

Same as Put[], but operates on a stored expression.

Scope[{x:={a,b,c}},PutR[x,2,f],x]   -->   {a,f,c}

--------------------------------------------------------------------------------
PutEdgeLengths   "11"


--------------------------------------------------------------------------------
PutEdgeSupport   "11"


--------------------------------------------------------------------------------
PutNumbers   "11"

PutNumbers[f[4.,a,{5.,6.}],{7.,8.,9.}]   -->   f[7.,a,{8.,9.}]

--------------------------------------------------------------------------------
PutTree   "111"


--------------------------------------------------------------------------------
Quantile   "11"

Quantile[distribution,p] is the quantile function.
Distributions are the same as for Random[].

--------------------------------------------------------------------------------
Quit   ""

Quits the TREEFINDER kernel.

--------------------------------------------------------------------------------
Random   "1"

Random[_distribution_] generates a random number drawn from _distribution_.

 _distribution_ is one of

  SampleD[data]
  NormalD[mu,sigma]
  StudentTD[n]
  ChiSquareD[n]
  FRatioD[n1,n2]
  BetaD[a,b]
  CauchyD[a,b]
  ChiD[n] )
  ExponentialD[lambda]
  ExtremeValueD[alpha,beta]
  GammaD[alpha,beta]
  HalfNormalD[theta]
  LaplaceD[mu,beta]
  LogisticD[mu,beta]
  LogNormalD[mu,sigma]
  ParetoD[k,alpha]
  RayleighD[sigma]
  UniformD[min,max]
  WeibullD[alpha,beta]
  BernoulliD[p]
  BinomialD[n,p]
  DiscreteUniformD[n]
  GeometricD[p]
  HypergeometricD[n,nsucc,ntot]
  LogSeriesD[theta]
  NegativeBinomialD[n,p]
  PoissonD[mu]


--------------------------------------------------------------------------------
RandomBoolean   ""

RandomBoolean[]   -->   True    (* maybe *)

--------------------------------------------------------------------------------
RandomInteger   "11"

RandomInteger[3,9]   -->   7      (* maybe *)

--------------------------------------------------------------------------------
RandomPhylogeny   "1."

RandomPhylogeny[ _species_list_ , _options_ ] generates a random phylogeny.

   option                 type      default
  ...........................................
   WithEdgeLengths        BOOLEAN   TRUE
   TreeRadius             REAL      RandomReal[0.25,0.75]
   EdgeLengthVariation    REAL      0.1
   MinimumEdgeLength      REAL      -1.0

   parameter          form
  ...........................................
   _species_list_     {"A. sp.","B. sp.","C. sp.","D. sp."}



--------------------------------------------------------------------------------
RandomReal   "11"

RandomReal[3.5,17.5]   -->   6.09945   (* maybe *)

--------------------------------------------------------------------------------
Randomize   "1{1}"

Randomizes the order of arguments.

Randomize[{1,2,3,4,5}]    -->   {4,3,1,2,5}    (* maybe *)

--------------------------------------------------------------------------------
Range   "1"


--------------------------------------------------------------------------------
Rank   "1"

Rank[{{a,b,c},{d,e,f}}]   -->   2
Rank[a]   -->   0
Rank[{a}]   -->   1
Rank[{{a}}]   -->   2

--------------------------------------------------------------------------------
Read   "1."


--------------------------------------------------------------------------------
ReadLines   "1."


--------------------------------------------------------------------------------
ReconstructPhylogeny   "1."

ReconstructPhylogeny[ _data_ , _options_ ] reconstructs a phylogeny. A
reconstruction report will be returned. Data partitioning will be assumed if
filter sequences are present in the data and if the PartitionRates option is
provided.

  Options:

   option                     type       default
  ...............................................
   SubstitutionModel          _model_
   PartitionRates             _prat_
   WithEdgeSupport            BOOLEAN    TRUE
   NReplicates                INTEGER    1000
   Tree                       _tree_
   GroupwiseEdgeLengths       _tree_
   StartTrees                 _tree_
   FirstTreeOnly              BOOLEAN    TRUE
   SearchDepth                INTEGER    2
   ResolveMultifurcations     BOOLEAN    FALSE
   EdgeOptimizationOff        BOOLEAN    FALSE
   IterationLimit             INTEGER    1000
   AcceptFlatness             BOOLEAN    FALSE
   AppendSitewiseRates        SYMBOL
   AppendSitewiseLikelihoods  SYMBOL
   AppendPairwiseDistances    SYMBOL
   Verbose                    BOOLEAN    TRUE


  The reconstruction report is a list of lists of the following rules:

   symbol                form       description
  .....................................................................

   Likelihood            REAL
   Phylogeny             _tree_
   GroupwiseEdgeLengths  _tree_
   SubstitutionModel     _model_
   OSubstitutionModel    _model_
   OEdgeOptimizationOff  BOOLEAN
   NSites                INTEGER    number of site patterns
   Checksum              INTEGER    data checksum
   PartitionKeys         _pkey_
   PartitionRates        _prat_
   OPartitionRates       _prat_
   NSitesPartitionwise   _plen_     partionwise number of site patterns
   FilterNames           _fnam_
   LikelihoodTime        REAL       total time consumed by the likelihood function
   LikelihoodMemory      INTEGER    memory used by the likelihood function


  Special expressions used in options and reports:

   parameter    form
  .....................................................................
   _data_           "filename"
                or  {"a":"TCAG","b":"TTAG","c":"TCAA","d":"GCAG"}
   _tree_           {"a":0.1,"b":0.2,{"c":0.1,"d":0.1}:0.1}
                or  {_tree_ , _tree_ }
                or  "treefile"
   _model_      see program manual "Model Expressions"
   _prat_           { 2.4 , 1.1 , 5.7 }
                or  1.0   (options only)
   _plen_           { 234 , 234 , 234 }
   _pkey_           { 11 , 12 , 13 }
   _fnam_           { "fil1" , "fil2" }


  All rules except the 'Phylogeny' are optional. To access parts of the report,
  use 'Get' with the operator |

  Given that the variable 'report' contains a report, one can get the
  likelihood of the first tree with:

  report|1|Likelihood

  The likelihood of the second, third, etc. tree, respectively:

  report|2|Likelihood
  report|3|Likelihood

  The options starting wit O... in a report are the original options used for
  ML reconstruction, while the corresponding options without O.. are the
  results. They contain information on parameter optimization. The O..-options
  are needed to exactly reproduce the computation of likelihood in parametric
  bootstrapping.



--------------------------------------------------------------------------------
RedrawPlot   "1."


--------------------------------------------------------------------------------
RedrawTree   "1."


--------------------------------------------------------------------------------
Remove   "11"

Remove[f[x,y,z[1,2]],{2}]   -->   f[x,z[1,2]]
Remove[f[x,y,z[1,2]],{3,2}]   -->   f[x,y,z[1]]

--------------------------------------------------------------------------------
RemoveR   "01"

Same as Remove[], but operates on a stored expression.

Scope[{x:={a,b,c}},RemoveR[x,2],x]   -->   {a,c}

--------------------------------------------------------------------------------
RemoveDirectory   "1"

RemoveDirectory[directoryname] removes a directory.

--------------------------------------------------------------------------------
RemoveEdgeData   "1"

RemoveEdgeData[tree] removes edge lengths and edge support from a tree.

--------------------------------------------------------------------------------
RemoveEdgeLengthIntervals   "1"

Removes edge length intervals from a tree.

--------------------------------------------------------------------------------
RemoveEdgeLengths   "1"

RemoveEdgeLengths[tree] removes edge lengths from a tree.

--------------------------------------------------------------------------------
RemoveEdgeSupport   "1"

RemoveEdgeSupport[tree] removes edge support from a tree.

--------------------------------------------------------------------------------
RemoveFile   "1"

RemoveFile[filename] removes a file.

--------------------------------------------------------------------------------
RemoveFilters   "1"


--------------------------------------------------------------------------------
RemoveFirstBranch   "1"


--------------------------------------------------------------------------------
RemoveGaps   "1"

RemoveGaps[data] removes all alignment gaps '-' from a sequence alignment.

--------------------------------------------------------------------------------
RemoveHypothesisData   "1"

RemoveHypothesisData[report] removes all hypothesis data fields from a
reconstruction report, i.e. all but Phylogeny->, Weight->, Meaning->, Comment->.

--------------------------------------------------------------------------------
RemoveSpace   "1"

RemoveSpace[" 1 2 3 "]   -->   "123"

--------------------------------------------------------------------------------
RemoveTips   "11"

RemoveTips[{"3",{"0",{{"1","2"},"5"}},{"4",{"6","7"}}},{"2","6","0"}]   -->   {{"7","4"},{"5","1"},"3"}

--------------------------------------------------------------------------------
Replace   "10"   -|

1-|{1->2}   -->   2
1[1,1[1],1]-|{1->2}   -->   1[1,1[1],1]

--------------------------------------------------------------------------------
ReplaceComponents   "10"   *|

1[1,1[1],1]*|{1->2}   -->   2[2,1[1],2]
1[1,1[1],1]*|{1[1]->2}   -->   1[1,2,1]

--------------------------------------------------------------------------------
ReplaceContents   "10"   ^|

1[1,1[1],1]^|{1->2}   -->   1[2,1[1],2]
1[1,1[1],1]^|{1[1]->2}   -->   1[1,2,1]

--------------------------------------------------------------------------------
Reroot   "11"

Roots or Reroots a tree.

Reroot[{"a",{"b",{{"c","d"},"e"}},{"f","g"}},4]   -->   {"c",{{{{"g","f"},"a"},"b"},"e"},"d"}

--------------------------------------------------------------------------------
ResampleSequences   "1"


--------------------------------------------------------------------------------
Return   "1"

Exec[<<Return[11],22>>]   -->   11

--------------------------------------------------------------------------------
Reverse   "1"

Reverse[{1,2,3,4,5}]   -->   {5,4,3,2,1}

--------------------------------------------------------------------------------
Rgamma   "1"

Numerical function.

--------------------------------------------------------------------------------
RobinsonFoulds   "11"

Robinson and Foulds topological distance.

--------------------------------------------------------------------------------
Roll

a,b,c,d,e, 4,Roll   -->   a,c,d,e,b
a,c,d,e,b, -4,Roll   -->   a,b,c,d,e

--------------------------------------------------------------------------------
Rtol   "0{0}"

Rtol[0.0001, 2300.==2301. ]   -->   False
Rtol[0.01,   2300.==2301. ]   -->   True

--------------------------------------------------------------------------------
Rule   "0{1}"

Represents a rule or option.

--------------------------------------------------------------------------------
Save   "11"

Save[expression,filename] saves any TL expression to the specified
file, including trees and sequence data.

--------------------------------------------------------------------------------
SaveDistances   "11."


--------------------------------------------------------------------------------
SaveList   "11"


--------------------------------------------------------------------------------
SaveLowerTriangle   "11"


--------------------------------------------------------------------------------
SaveReport   "11"

Saves a reconstruction report to the specified file. Instead of the
report, one can alternatively provide a list of trees, which will be
converted into a report.

--------------------------------------------------------------------------------
SaveSequences   "11."

SaveSequences[ _data_ , _filename_ , _options_ ] saves a nucleotide matrix to
the specified file.

   option            type       default
  ...........................................
   Format            _format_     "TREEFINDER"
   BasesPerLine      INTEGER    60
   BasesPerGroup     INTEGER    10
   Compact           BOOLEAN    FALSE
   Dotted            BOOLEAN    FALSE
   Lowercase         BOOLEAN    FALSE
   Uppercase         BOOLEAN    FALSE
   TAsU              BOOLEAN    FALSE
   IOption           BOOLEAN    FALSE
   UOption           BOOLEAN    FALSE
   IncludeTree       _trees_

   parameter    form
  ...........................................
   _data_       {"a":"TCAG","b":"TTAG","c":"TCAA","d":"GCAG"}
   _format_       "TREEFINDER" or   "PHYLIP" or   "FASTA"
   _tree_       {"a":0.1,"b":0.2,{"c":0.1,"d":0.1}:0.1}
   _trees_      _tree_
                or {_tree_ , _tree_ }
                or   "treefile"


--------------------------------------------------------------------------------
SaveText   "11"


--------------------------------------------------------------------------------
SaveTree   "11."

SaveTree[ _trees_ , _filename_ , _option_ ] saves the first tree found
in a list or report to a file in the specified format.

   option         type       default
  ...........................................
   Format         STRING       "TL"

   parameter    form
  ...........................................
   _filename_   STRING
   _format_     "PHYLIP" or "NEWICK" or "NEXUS" or "TL"
   _tree_       {"a":0.1,"b":0.2,{"c":0.1,"d":0.1}:0.1}
   _trees_      _tree_
                or {_tree_ , _tree_ }
                or a reconstruction report, see 'ReconstructPhylogeny'


--------------------------------------------------------------------------------
SaveTreeList   "11."

Similar to SaveTree[], but saves all trees in a list or report.

--------------------------------------------------------------------------------
SaveUpperTriangle   "11"


--------------------------------------------------------------------------------
ScaleEdgeLengths   "11"


--------------------------------------------------------------------------------
ScaleEdgeSupport   "11"


--------------------------------------------------------------------------------
Scan   "1{1}"


--------------------------------------------------------------------------------
Scope   "0{0}"

x , Scope[{x},x=3,x,x+1] , x   -->   x , 3 , 4 , x
x , Scope[{x:=3},x,x+1] , x   -->   x , 3 , 4 , x

--------------------------------------------------------------------------------
SelectCodonPositions   "11"


--------------------------------------------------------------------------------
SelectDistances   "11"


--------------------------------------------------------------------------------
SelectFilters   "11"


--------------------------------------------------------------------------------
SelectPartitions   "11"


--------------------------------------------------------------------------------
SelectSequences   "11"


--------------------------------------------------------------------------------
Set   "01"

Assigns a new value to an existing variable or creates a new one.

--------------------------------------------------------------------------------
SetFilePosition   "11"


--------------------------------------------------------------------------------
SetMask   "01"

Assigns a mask to a function.

--------------------------------------------------------------------------------
SimulateSequences   "1"

Simulates sequences along a reconstruction report.

--------------------------------------------------------------------------------
Sin   "1"

Numerical function.

--------------------------------------------------------------------------------
Sinh   "1"

Numerical function.

--------------------------------------------------------------------------------
Sign   "1"

Sign[12]   -->   1
Sign[-1.2]   -->   -1
Sign[0]   -->   0

--------------------------------------------------------------------------------
Simplify   "1"

Simplify['(/1/(g/1))]   -->   /g

--------------------------------------------------------------------------------
Skip   "1."


--------------------------------------------------------------------------------
Sort   "1."

Sort[{8,3,aa,2,b,5:fg,4,2,a}]   -->   {2,2,3,4,8,a,aa,b,5:fg}
Sort[f[d,a,e,b,f,c]]   -->   f[a,b,c,d,e,f]
Sort[Randomize[f[d,a,e,b,f,c]]]   -->   f[a,b,c,d,e,f]

--------------------------------------------------------------------------------
SortHypotheses   "11"


--------------------------------------------------------------------------------
Spell   "1[1]"

Spell[expression] writes an expression to stdout.
Spell[expression,stream] writes an expression into a stream.
Spell writes the contents of strings rather than their TL
representaion. Escape sequences will be unescaped.

--------------------------------------------------------------------------------
Sqrt   "1"

Square root.

--------------------------------------------------------------------------------
Stack

Lists the things on the stack.

a,b,c,d,e, Stack   -->   a,b,c,d,e, {e,d,c,b,a}

--------------------------------------------------------------------------------
StackLength

Counts the number of things on the stack.

a,b,c,d,e, StackLength   -->   a,b,c,d,e, 5

--------------------------------------------------------------------------------
StandardDeviation   "1"

StandardDeviation[{5,7,5,7,5,6,7,5,7}]   -->   1.

--------------------------------------------------------------------------------
StandardizeAASequences   "1"


--------------------------------------------------------------------------------
StandardizeDNASequences   "1"


--------------------------------------------------------------------------------
StandardizeRNASequences   "1"


--------------------------------------------------------------------------------
StandardizeTree   "1."

StandardizeTree[tree] rearranges a tree into a canonical form, which
allows comparing it with other standardized trees.

StandardizeTree[{"y",{{"x","a"},"c"},"e"}]   -->   {{"a","x"},"c",{"e","y"}}
StandardizeTree[{"y",{{"x","a"},"c"},"e"},HoldFirst->True]   -->   {"y",{{"a","x"},"c"},"e"}

--------------------------------------------------------------------------------
Sto   "{1}0"

Same as set, but with reversed arguments.

--------------------------------------------------------------------------------
StringLength   "1"

StringLength["degf"]   -->   4

--------------------------------------------------------------------------------
Sub   "11"   -

Subtraction.

Sub[7,3]   -->   4
7-3   -->   4

--------------------------------------------------------------------------------
SubR   "01"   -=

Same as Sub[], but operates on a stored expression.

Scope[{x:=3},x-=1,x]   -->   2

--------------------------------------------------------------------------------
Sum   "00{0}"

Roughly equivalent to Table[...]@Add .

Sum[i,(=i,1:4=)]   -->   10

--------------------------------------------------------------------------------
Swap

Exchanges stack positions 1 and 2.

a,b,c,d,e, Swap   -->   a,b,c,e,d

--------------------------------------------------------------------------------
SwapBranches   "111"

SwapBranches[{{"A","B"},{"C","D"},"E"},3,5]  -->   {{"A",{"C","D"}},"B","E"}

--------------------------------------------------------------------------------
System   "1"

System[commandstring] invokes a system command or program
as one would do from a terminal window.

--------------------------------------------------------------------------------
Table   "00{0}"

Table[f[i],(=i,1:4=)]   -->   {f[1],f[2],f[3],f[4]}
Table[f[i],(=i,1:7:2=)]   -->   {f[1],f[3],f[5],f[7]}
Table[f[i],(=i,{a,b,c,d}=)]   -->   {f[a],f[b],f[c],f[d]}
Table[f[i,j],(=i,1:3,j,5:7=)]   -->   {f[1,5],f[2,6],f[3,7]}
Table[f[i,j],(=i,1:2=),(=j,1:2=)]   -->   {{f[1,1],f[1,2]},{f[2,1],f[2,2]}}
Table[i,(=j,1:4=),(=i,1:j=)]   -->   {{1},{1,2},{1,2,3},{1,2,3,4}}
Table[i,(=i,1:7=)]   -->   {1,2,3,4,5,6,7}
Table[f[i,j],(=i,1:7,j,{a,b,c}=)]   -->   {f[1,a],f[2,b],f[3,c]}
Table[If[i==4,Break];i,(=i,1:7=)]   -->   {1,2,3}
Table[If[i<=4,Continue];i,(=i,1:7=)]   -->   {5,6,7}

--------------------------------------------------------------------------------
TakeAll   "0"

Scope[{li:={a,b,c}},TakeAll[li]]   -->   {a,b,c}
Scope[{li:={a,b,c}},TakeAll[li],Drop,li]   -->   {}

--------------------------------------------------------------------------------
TakeFirst   "0"

Scope[{li:={a,b,c}},TakeFirst[li]]   -->   a
Scope[{li:={a,b,c}},TakeFirst[li],Drop,li]   -->   {b,c}

--------------------------------------------------------------------------------
TakeLast   "0"

Scope[{li:={a,b,c}},TakeLast[li]]   -->   c
Scope[{li:={a,b,c}},TakeLast[li],Drop,li]   -->   {a,b}

--------------------------------------------------------------------------------
Tan   "1"


--------------------------------------------------------------------------------
Tanh   "1"

Numerical function.

--------------------------------------------------------------------------------
TestTopologies   "11."


--------------------------------------------------------------------------------
ThreadQuantile   "11"


--------------------------------------------------------------------------------
ThreadMean   "1"


--------------------------------------------------------------------------------
ThreadMeanInterval   "1"


--------------------------------------------------------------------------------
ThreadMedian   "1"


--------------------------------------------------------------------------------
ThreadMaximum   "1"


--------------------------------------------------------------------------------
ThreadMinimum   "1"


--------------------------------------------------------------------------------
ThreadOverLists


--------------------------------------------------------------------------------
ThreadRange   "1"


--------------------------------------------------------------------------------
ThreadVariance   "1"


--------------------------------------------------------------------------------
ThreadStandardDeviation   "1"


--------------------------------------------------------------------------------
Throw   "1"

Throw[message] stops evaluation. The nearest enclosing Catch[] will return
the message.

--------------------------------------------------------------------------------
Time   ""

Returns the number of seconds since 1970.

--------------------------------------------------------------------------------
TipToTipDistances   "1"

TipToTipDistances[{{"a":1,"b":2}:3,{"c":4,"d":5}:6}]   -->   {{"a","b","c","d"},{3.,14.,15.,15.,16.,9.}}
TipToTipDistances[{{"a":0,"b":1}:-1,{"c":6,"d":7}:2}:-4]   -->   {{"a","b","c","d"},{3.,14.,15.,15.,16.,9.}}

--------------------------------------------------------------------------------
ToASCII   "1"

ToASCII["G"]   -->   71

--------------------------------------------------------------------------------
ToCharacter   "1"

ToCharacter[99]   -->   "c"

--------------------------------------------------------------------------------
ToLowercase   "1"

ToLowercase["J"]   -->   "j"

--------------------------------------------------------------------------------
ToRealArray   "1"


--------------------------------------------------------------------------------
ToRealList   "1"


--------------------------------------------------------------------------------
ToString   "1"

ToString[4.3]   -->   "4.3"
Oprec[5,ToString[Pi]]   -->   "3.1416"

--------------------------------------------------------------------------------
ToUppercase   "1"

ToUppercase["j"]   -->   "J"

--------------------------------------------------------------------------------
Transform   "10"   =|

Transform[expression,rules] tries to transform an expression by applying rules.

1[1,1[1],1]=|{1->2}   -->   2[2,2[2],2]
1[1,1[1],1]=|{1[1]->2}   -->   1[1,2,1]

--------------------------------------------------------------------------------
TransitionProbabilities   "11"


--------------------------------------------------------------------------------
Transpose   "1"

Transposes a matrix.

Transpose[{{a,b},{c,d},{e,f}}]   -->   {{a,c,e},{b,d,f}}
Transpose[{{a,b,7},{c,d,2}}]   -->   {{a,c},{b,d},{7,2}}

--------------------------------------------------------------------------------
TreeLength   "1"


--------------------------------------------------------------------------------
Type   "1"

Type[32]   -->   Integer
Type["32"]   -->   String

--------------------------------------------------------------------------------
Unbuild

f[a,b,c,d,e], Unbuild   -->   a,b,c,d,e,f

--------------------------------------------------------------------------------
Uncompress   "1"

Uncompress[Compress["abdgh"]]   -->   "abdgh"

--------------------------------------------------------------------------------
Unhold   `

x=>3+4   -->   x=>3+4
x=>`(3+4)   -->   x=>7

--------------------------------------------------------------------------------
Unprotect   "0"


--------------------------------------------------------------------------------
Unroot   "1"

Unroots a tree.

--------------------------------------------------------------------------------
Until   "00"

Until[test,proc] evaluates proc repeatedly until test gives True.

Scope[{x:=0}, Until[x>100,x+=17],x ]   -->   102

--------------------------------------------------------------------------------
Unwrap   "11"

Unwrap[{a,f[b],c},2]   -->   {a,b,c}
Unwrap[f[u,h[8]],-1]   -->   f[u,8]

--------------------------------------------------------------------------------
UnwrapR   "01"

Same as Unwrap[], but operates on a stored expression.

Scope[{x:={a,f[b],c}},UnwrapR[x,2],x]   -->   {a,b,c}

--------------------------------------------------------------------------------
Variance   "1"


--------------------------------------------------------------------------------
While   "00"

While[test,proc] evaluates proc repeatedly while test gives True.

Scope[{x:=0}, While[x<100,x+=17],x ]   -->   102

--------------------------------------------------------------------------------
Wrap   "111"

Wrap[{a,b,c},2,f[]]   -->   {a,f[b],c}
Wrap[f[u,h[8],35],-1,z[4]]   -->   f[u,h[8],z[35,4]]

--------------------------------------------------------------------------------
WrapR   "011"

Same as Wrap[], but operates on a stored expression.

Scope[{x:={a,b,c}},WrapR[x,2,f[]],x]   -->   {a,f[b],c}

--------------------------------------------------------------------------------
Write   "1[1]"

Write[expression] writes an expression to stdout.
Write[expression,stream] writes an expression into a stream.

--------------------------------------------------------------------------------
WriteLines   "11."


--------------------------------------------------------------------------------
Xor   "{1}"   ^^

Logical eXclusive OR.

True^^False   -->   True
Xor[True,True]   -->   False
False ,True ,Xor   -->   True

--------------------------------------------------------------------------------
ZeroNumbers   "1"

ZeroNumbers[{{2.[3.,4.][5.,6.,7.]},8.}]   -->   {{0.[0.,0.][0.,0.,0.]},0.}
