USER VARIABLES
From TNT
Contents |
DECLARATION
User variables are declared as: var: name_a name_b name_c[dims_for_c] ;
this declares name_a and name_b as simple variables, and an array name_c (of a number of values, or cells, equal to dims_for_c). If several declarations are repeated (i.e., new instances of var:), the new declaration will place the first declared variable in the memory area that is contiguous to the last variable declared in the previous instance of var:. It is possible to un-declare variables (for example, to alleviate the use of memory by the macro system), with var – name; or var – N (this eliminates from the list all the variables that had been declared after variable called name, or numbered as N, inclusive). If no name or number is specified, then all the variables that had been declared in the current input file are un-declared. For alternative ways to declare variables, see documentation of TNT. Variable declaration is internal of every input file; every time an input file, al the variables that had been declared within that input file are automatically eliminated. If a variable is declared with the same name that had been used in a previous input file (not yet closed, from which the current one was called), then the name refers to the variable in the current file (variables in other input files can be accessed only if they have a different name).
SETTING VALUES
To asign a value to a variable, the set command is used, followed by the name (and cell, if an array) of the variable, and an expression (to indicate the value that the variable will take). A few expressions (=internal variables) automatically transfer values to array (such as freqlist, freqdlist, bremlist, uplist, downlist, randomlist; see help+ for details), case in which the variable given to set has to have enough cells available. The expression states also can, optionally, return values as uni- or bi-dimensional arrays (replacing the number of characters, or taxa, or both, by a period). As for the expression itself, if it is replaced by ++ the value of the variable is increased in one, with -- it is decreased, with +=X it is increased in X, and with - =Y it is decreased in Y. It is possible to store a string in a variable (case in which, you have to be careful not to overwrite variables adjacent in memory; the program does NOT check for this error), giving after the name of the variable the symbol "$" followed by the string (strings are accessed in the same way as they are set, see below). Last, it is also possible to assign values to a complete array, with the setarray command.
ACCESS
Once user variables have been assigned a value, it is possible to use that value in comparisons, calculations, etc. Enclosing the name (or number) of the variable within single quotes is equivalent to writing the value that has been assigned to the variable, in any context. It is this feature which allows using these variables in regular TNT commands. As example, consider a case where we want to select a taxon at random to be deactivated. The expression getrandom is recognized exclusively within the context of the macro commands (i.e. those listed under help+), and therefore we could NOT do something like:
TAXCODE - getrandom[0 ntax] ;
since the TAXCODE command is not a macro command and it expects as arguments(s) nothing more than numbers, taxon names, or taxon groups. This would have to be done as follows:
var: thetax ; /* declare variable... */ set thetax getrandom[0 ntax] ; /* ... and assign to it a random number, between 0 and number of taxa – 1 */ TAXCODE - 'thetax' ; /* deactivate taxon */
The number of decimals with which the value of the variable is read is (by default) the one that has been set with macfloat N (default = 5). It is possible to give a specific format to the number (useful for creating formatted output, see below, under FORMATTED OUTPUT).
In the case of arrays, it is possible to convert the variable into a series of values automatically. Thus, if the variable called (for example) listaxa contains numbers 4, 8, 3 , 12, and 15 as its first 5 values (cells 0-4), the expression 'listaxa[0-4]' is equivalent to writing "4 8 3 12 15" (for example, TAXCODE - 'listaxa[0-4]' will deactivate those five taxa). If the second number is followed by the symbol & and a number N, then character ASCII N is used as separator of the numbers: 'listaxa[0-4 &43]' is equivalent to writing "4+8+3+12+15". This is useful to create lists containing a number of elements that is unknown before running the script. The following script lists the taxa which have been deactivated:
var: numelements
dalist[ (ntax + 1) ] ;
set numelements 0 ;
loop 0 ntax
if ( isactax [ #1 ] ) continue ; end
set dalist [ 'numelements' ] #1 ;
set numelements ++ ;
stop
macfloat 0 ;
QUOTE A total of 'numelements' taxa are currently inactive: ;
QUOTE 'dalist [ 0 – ('numelements'-1) ]' ; /* we dont know ahead of time how many
numbers we print! */
PROC/;
If instead of enclosing the number/name of the variable
within quotes, it is preceded by the symbol $, then the variable
is interpreted as the string the begins at that position. This
can also be applied to some special cases (the meaning of which, I
hope, will be obvious to the reader): $dataset, $taxon N,
$character N, $state C S, $ttag N, $host N.
PLOTS/CORRELATION
It is also possible to produce (veeery simple) plottings of the values in one (or two) array(s), with the "var+" option. The option "var&" calculates a lineal regression between two variables (the values are stored in the internal variables regr, regalfa, y regbeta, of obvious meaning). See "help+var" for details. The maketable command, through the specification of an array (or two), allows displaying the values of the array in table format (a double table, in case two arrays are specified). See "help maketable;" for details on how to use this command.
