Navigation Banner
 
 

+ Operation
  Operation of addition.
Syntax  x+y
Notes Both operands are either numbers or matrices. In the latter case, the dimensions of the operands must be equal, lest '+' return an error. Additionally, '+' performs string concatenation.
Examples
-- String Concatenation:
   str = "Hello "+"World";
--'str' now holds "Hello World".
 Last modified: 5/11/2000
- Operation
  Operation of subtraction.
Syntax  x-y, or -x (unary minus)
Notes Both operands are either numbers or matrices. In the latter case, the dimensions of the operands must be equal, lest '-' return an error.
Unary minus is equivalent to 0-x.
Examples
 Last modified: 5/11/2000
* Operation
  Operation of multiplication.
Syntax  x*y, or , x y(implied multiplication).
Notes Multiplication accepts either:
  • Two numbers
  • Matrix followed by a number (term wise multiplication of the matrix).
    Note: number * matrix will return an error.
  • Two matrices, whose dimensions are compatible, i.e the number of columns in the first argument is the same as the number of rows in the 2-nd.
Examples
2(x+y)

{{1,2}{3,4}} (-1)
(returns {{-1,-2}{-3,-4}})

{{1}{1}}{{2}{3}}
(returns {{6}}).

 Last modified: 5/11/2000
/ Operation
  Operation of floating point division.
Syntax  x/y
Notes Works on numbers only. To divide a matrix by a number, use multiplication by the reciprocal of that number.
Examples
3/4
 Last modified: 5/11/2000
% Operation
  Operation of remainder of integer division.
Rounds both arguments and then returns the remainder of integer division.
Syntax  x%y
Notes Works on numbers only.
Examples
5%3 (returns 2)
 Last modified: 8/17/1999
$ Operation
  Operation of integer division.
Rounds both arguments and then returns the result of integer division.
Syntax  x%y
Notes
Examples
5$3 (returns 1)
 Last modified: 8/17/1999
! Operation
  Operation of negation.
If the number is non-zero returns 0 (false), otherwise returns 1(true).
Syntax  !x
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
&& Operation
  Operation of conjunction (logical AND).
If both arguments are non-zero returns 1(true), otherwise returns 0.
Syntax  x&&y
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
|| Operation
  Operation of disjunction (logical OR).
If both arguments are 0 returns 0(false), otherwise returns 1 (true).
Syntax  x||y
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
^ Operation
  Operation of raise to power.
Returns x raised to power y.
Syntax  x^y
Notes Works on numbers only. x must be positive.
Examples
 Last modified: 8/17/1999
== Operation
  Operation 'equal'.
If the numbers are equal (or rather if the |x-y|/min(|x|,|y|)
Syntax  x==y
Notes Works on numbers and strings.
Examples
 Last modified: 1/19/2000
!= Operation
  Operation 'not equal'.
If x is not equal to y (within floating point precision) returns 1, otherwise returns 0.
Syntax  x!=y
Notes Works on numbers and strings.
Examples
 Last modified: 1/19/2000
= Batch language command
  Value assignment operator. Assigns the current value of the rhs to the lhs. To create dependancies use ':='.
Syntax  LHS = RHS;
Notes
Examples
a=2;
b=3;
c:=a+b;
d=a+b;
a=4;
fprintf (stdout, a," ",b," ",c," ",d);
-- outputs 4 3 7 5.
 Last modified: 8/19/2002
:= Batch language command
  Dependance assignment operator. Assigns the formula defined by the rhs to the lhs. This operator should be used to constrain variables before optimization.
Syntax  LHS := RHS;
Notes
Examples
a=2;
b=3;
c:=a+b;
d=a+b;
a=4;
fprintf (stdout, a," ",b," ",c," ",d);
-- outputs 4 3 7 5.
 Last modified: 5/11/2000
[] Operation
  Matrix or string access operation. In a matrix, can be used to access any given element, indexed by row and column position.
Syntax  Matrices: Matrix_Ident[row][column];
Strings: String_Ident[position];
or
String_Ident[start_index][end_index];
Notes
For strings, the [] operation returns the character at a given position in the string (indexed from 0). []can also be used to generate a substring of a given string.

Indexing starts at 0. For row or column vectors single index will suffice, i.e. v[0][2] is the same as v[2] if v is a row vector.

Examples
test_string = "Hello cruel world";
test_substring = test_string[0][4]; // "Hello"
 Last modified: 8/20/2002
Abs Built-in function
  Absolute value.
If x is a number, returns |x|.
If x is a matrix, returns maximum absolute value among matrix elements, unless x is vector in which case the euclidean norm is returned. If x is a string, returns the length of the string.
Syntax  Abs(x)
Notes
Examples
Abs({{1,2}{-4,3}})
returns 4.
Abs ("foobar")
returns 6.
Abs({{1,1}}) returns 1.41421 (i.e. the square root of 2).
 Last modified: 8/9/2002
ALLOW_BOUNDARY Constant
  If true (default) then variables are allowed to assume boundary values.
Syntax  ALLOW_BOUNDARY = 0 or 1;
Notes
Examples
 Last modified: 8/17/1999
Arctan Built-in function
  Inverse Tangent. Returns the inverse tangent of x.
Syntax  Arctan(x)
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
ASSIGNED_SEED Built-in function
  If ASSIGNED_SEED is set, then it is fed to the standard random number generator seed function. Can be used to replicate simulation results.
Syntax  ASSIGNED_SEED=value;
Notes
Examples
 Last modified: 1/19/2000
BASESET Data File formatting instruction
  BASESET is used to indicate what characters form the fundamental states of the data.
Syntax  $BASESET:"new set" (new line char)
Notes If "new set" = "BASE20", the data is assumed to contain aminoacid info (with standard ambigutity characters).

Must be present in the file before any data begins and before any TOKEN directives are issued. The new character set is simply a string where each character is understood as a new state and the first character is mapped to state '0Õ, the 2nd - to state '1'etc.

Does not apply to NEXUS files.

Examples
$BASESET:"ACGU"
(RNA code)

$BASESET:"01"
(binary data)

 Last modified: 8/20/2002
Beta Built-in function
  The 'Beta'function. Beta(x,y)=Gamma(x)Gamma(y)/Gamma(x+y).
Syntax  Beta(x,y)
Notes x and y should not be negative integers.
Examples
 Last modified: 8/17/1999
Bootstrap Batch language command
  Can be used to create samples with replacement of blocks of columns of 'unit' length of existing data sets or data set filters.
Syntax  DataSetFilter = Bootstrap (datasetid, unit, vertical partition);
Notes datasetid must refer to an existing data set or a data set filter. 'unit' is a positive integer. The last argument is optional.

The specification of vertical partition is identical to that of 'CreateFilter'.

Examples
 Last modified: 8/20/2002
BRACKETING_PERSISTENCE Constant
  In conjunction with randomized order bracketing, specifies, how many times, on average each variable will be bracketed. Defualt value is 2.5.
Syntax  BRACKETING_PERSISTENCE=value;
Notes
Examples
 Last modified: 8/17/1999
BranchCount Built-in function
  When applied to a tree variable, returns the number of internal branches in the tree.
Syntax  res = BranchCount(tree_ident);
Notes
Examples
 Last modified: 1/19/2000
BranchLength Built-in function
  'BranchLength' returns the expected number of substitution along a given branch using the model and parameter value currently attached to the branch. The value of 0 is returned for undefined cases.
Syntax  BranchLength (treeID, branch index);
Notes 'treeID' is an exisiting tree;
'branch index' is the integer index of the branch whose length we wish to retrieve, in the pre-order traversal sequence.
Examples
 Last modified: 5/11/2000
BranchName Built-in function
  Returns a string containing the name of an internal node of the tree.
Syntax  res = TipName(tree_ident, node_index);
Notes Valid index range is 0 to BranchCount (tree_ident)-1. The name of the node is of the form 'Node1' rather than 'Tree.Node1'.
Examples
Tree tr = ((a,b)int1,c,d);
tName = BranchName (tr, 0);

Result: "int1".

 Last modified: 5/11/2000
break Batch language command
  A loop termination command. When encountered within any for, while or do..while loop, causes the execution of the loop to stop, and transfers control to the first statement following the loop.
Syntax  break;
Notes A loop termination command. When encountered within any for, while or do..while loop, causes the execution of the loop to stop, and transfers control to the first statement following the loop.
Examples
for (i=5;i<100;i=i+1)
{
   ;if (Random(0,i)>i-1)
     {    
     break;
   }
}
 Last modified: 8/19/2002
CACHE_SUBTREES Constant
  If true (default) then HyPhy uses a caching scheme to speed up likelihood caclulations. A little less memory is used if caching is turned off.
Syntax  CACHE_SUBTREES= 0 or 1;
Notes
Examples
 Last modified: 6/7/2001
Category Batch language command
  Used to define a category (rate variation) variable.
Syntax  category id = (number of intervals, weights, method for representation, density, cumulative, left bound, right bound,optional mean cumulative function);
Notes
-number of intervals: number of different categories;

-weights: probability for each interval. Could be set to Equal, or a single row matrix of weights, or a formula in terms of _n_, where _n_ runs from 0 to number of intervals:

-method for representation: How to pick a representative for each category-MEAN, MEDIAN or SCALED_MEDIAN. Only meaningful for variables coming from continuous distributions. SCALED_MEDIAN is the same as median, except the mean of the discrete approximation is scaled to match the mean of the continuos generator.

-density: the formula for the generating continuos density function (in terms of _x_). Leave blank to specify a discrete distribution

-cumulative: the formula for the cumulative probability function (in terms of _x_). Leave blank if not known. Specify a row matrix of values for a discrete distribution here

-left bound: left bound for _x_ in the continuous distribution

-right bound: right bound for _x_ in the continuous distribution

-optional mean cumulative function: if known, the formula for mean over interval (left bound,_x_) in terms of _x_.

Examples
See files in 'Examples'.
 Last modified: 8/19/2002
CATEGORY_SIMULATION_METHOD Constant
  Controls how category variables are simulated:
1 - use discrete distibution;
2(default) - when available, use continuous distribution.
Syntax  CATEGORY_SIMULATION_METHOD=1 or 2;
Notes
Examples
 Last modified: 5/11/2000
CChi2 Built-in function
  The cumulative Chi squared distribution.
CChi2(x,n) = P{t<x}, where t is a random variable with the Chi-squared n degrees of freedom distribution.
Syntax  CChi2 (x,n)
Notes n and x should be positive.
Examples
 Last modified: 5/11/2000
CGammaDist Built-in function
  The cumulative gamma distribution.
CGammaDist(x,a,b) = P{t<x}, where t has gamma distribution with the shape parameter a, and the 'mean' parameter b.
Syntax  CGammaDist(x,a,b)
Notes x and a should be positive.
Examples
 Last modified: 5/11/2000
ChoiceList Batch language command
  Used to present the user with a list of choices, and guides the user through the process of selecting one (or more) of them. If the user made a valid selection, then the string value of the selection is stored in the variable SELECTION_STRINGS.
Syntax  ChoiceList (result,"Title",selection length,skip flag,"option 1 name","option 1 description","option 2 name","option 2 description",...,"option N name","option N description"); or
ChoiceList (result,"Title",selection length,skip flag,object)
Notes 'result' holds the choice of the user. If the user selected one option only (triggered by, selection length flag) 'result' holds either -1 if the selection was cancelled, or the index of the selected option starting at 0. If more than option were selected 'result' is a vector with indices of selections. If the [0] element of 'result' is -1 then the selection process was cancelled.
"Title" is the title of the selection list
'selection length' indicates how many choices the user must make. 0 means that the user is allowed ti make an arbitrary (1 or more) number of choices
'skip flag' is either SKIP_NONE, so that all selections are available to the user or a vector of selection indices to skip
The list of selections afterwards is simply a collection of available choices.
You may place an object identifier nstead of the explicit list of selections. It could be:
1). A dataset (the selections are taxa names)
2). A datasetfilter (the selections are taxa names).
3). If this argument is the literal "LikelihoodFunction" then the list of currently defines likelihood functions will be generated.
4). If this argument is the literal LAST_MODEL_PARAMETER_LIST, then the list of parameters of the model which was last declared will be generated.
This list will later include other objects.
Examples
See TemplateBatchFiles.
 Last modified: 6/7/2001
CLEAR_FILE Constant
  Used as an argument to FPRINTF, forces the target file to be cleared.
Syntax  fprintf (file_name,CLEAR_FILE,);
Notes Use at the beginning of the file to clear a results file or something of the sort.
Examples
 Last modified: 1/19/2000
ClearConstraints Batch language command
  Used to remove constraints on variables.
Syntax  ClearConstraints(var1,var2,...,varN);
Notes All var's must reference existing variables.
Examples
ClearConstraints(tr.Node1.a,tr.Node1.b);
 Last modified: 8/17/1999
Columns Built-in function
  The number of columns function.
Returns the number of columns in a matrix.
Syntax  Columns(m)
Notes m must be a matrix
Examples
 Last modified: 8/17/1999
Combine Batch language command
  A command to merge several data sets into one. If the first argument is 'purge', then all the data sets used in the merge operation will be deleted after the operation is finished. The resulting data set contains all the data from the component data sets as stacked columns, i.e. column 1 is a vertical stack of all columns 1 from the component data sets.
Syntax  DataSet datasetid = Combine(purge,datasetid1,...,datasetidn);
Notes All 'datasetid' must refer to existing data sets. If the number of sites varies from data set to data set, the missing sites will be padded with deletion symbols. 'purge' is optional.
Examples
DataSet ds = Combine(data1,data2,data3);

or

DataSet ds = Combine(purge,data1,data2,data3);

 Last modified: 5/11/2000
Concatenate Batch language command
  A command to merge several data sets into one. If the first argument is 'purge', then all the data sets used in the merge operation will be deleted after the operation is finished. The resulting data set contains all the data from the component data sets as concatenated rows, i.e. row 1 is the concatenated rows 1 of all component data sets.
Syntax  DataSet datasetid = Concatenate(purge,datasetid1,...,datasetidn);
Notes All 'datasetid' must refer to existing data sets. If the number of species varies from data set to data set, the missing rows will be padded with deletion symbols. 'purge' is optional.
Examples
DataSet ds = Conacatenate(data1,data2,data3);

or

DataSet ds = Conacatenate(purge,data1,data2,data3);

 Last modified: 5/11/2000
ConstructCategoryMatrix Batch language command
  Produces a matrix of category assignments for the sites of data analyzed with category variables.
Syntax  CategoryMatrix (receptacle, likelihood_function, short_or_long);
Notes
'receptacle' is the matrix to store category assignments,
'likelihood_function' is a likelihood function identifier,
and short_or_long is a flag which indicates whether to produce a matrix which for each site will contain a row of conditional likelihoods for each category, or rather just the index of the maximally likely category.

The resulting matrix will contain a column for each site in the data (left to right).

If short_or_long is set to COMPLETE, the long matrix is produced. Any other value will generate a short matrix.

Examples
ConstructCategoryMatrix(cm, lf, COMPLETE);
 Last modified: 8/20/2002
continue Batch language command
  A loop 'forward'command. When encountered within any for, while or do..while loop, causes the rest of the commands within the loop to be ignored and forces execution back to the beginning of the loop.
Syntax  continue;
Notes
Examples
for (i=0;i<64;i=i+1)
{
 if ((i==48)||(i==50)||(i==56))
 {
  continue;
 }
 else
 {
  ...
 }
}
 Last modified: 8/19/2002
Cos Built-in function
  The cosine function.
Syntax  Cos(x)
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
COVARIANCE_PRECISION Constant
  A constant which determines what method is used by CovarianceMatrix in computing the numerical Hessian.
Syntax  COVARIANCE_PRECISION = 1 or 2;
Notes 1 - use a first order difference formula for partial derivatives (one function evaluation per cell) (Default)
2 - use a second order difference formula for partial derivatives (4 function evaluations per cell)
Examples
 Last modified: 8/20/2002
CovarianceMatrix Batch language command
  CovarianceMatrix computes the approximate covariance matrix for the MLE of a given likelihood function.
Syntax  CovarianceMatrix (result_matrix, likelihood_function_name);
Notes Use COVARIANCE_PRECISION to control how the Hessian is computed.
Examples
CovarianceMatrix (covMx, lf);
 Last modified: 4/25/2000
CreateFilter Batch language command
  Used to select portions of data sets for inclusion in analyses. 'datasetid' is the identifier of the data set to filter. 'unit' is the size of the basic state for analyses in terms of the charchter length.
Syntax  DataSetFilter dataSetFilterid = CreateFilter (datasetid,unit,vertical partition, horizontal partition, alphabet exclusions);
Notes Upon successful completion of this command, 4 variables are automatically created:
- dataSetFilterid species : number of species in the data set
- dataSetFilterid.sites: number of sites(columns) in the data set
- dataSetFilterid.unique_sites: number of unique sites in the data set,
dataSetFilterid.site_freqs: the vector of dimension dataSetFilterid.unique_sites, which contains the count of sites of type i, in cell i.

E.g., to use codons in analysis of nucleotide data, specify, unit to be 3. Vertical partition designates the sites to be used in analysis. Leaving it blank: "" includes all the sites.

datasetid must refer to an existing data set or a data set filter 'unit' is a positive integer. The last three arguments are optional.

Acceptable partition formats:
1). Explicit list:"0,1,4,5,10", includes sites 1,2,5,6,11 in analysis.
2). Intervals:"0-99", includes sites 1 through 100 in analysis.
3). Paired intervals:"0-9&20-29" includes sites 1,21,2,22,..,10,30 in analysis.
4). Composite:"0-5,7,10-15&20-25".
5). Boolean expression in terms of siteIndex. Includes all sites whose index renders the expression true.
6). Combs: for example "<011>" will select every 2nd and 3rd element of each triplet, "<10101>" - every 1st, 3rd and 5th element of each quintuplet.

The foregoing is also true for horizontal partition, with the exception of item 5, where siteIndex, should be replaced with species index.
Alphabet exclusions is a comma separated list of state not to be allowed in analysis.

Examples
DataSetFilter dsf = CreateFilter (ds,3,"","","TAA,TGA,TAG");

DataSetFilter dsf = CreateFilter (ds,1,"0-100");

DataSetFilter dsf = CreateFilter (ds,1,(siteIndex%3)==0);

 Last modified: 9/3/2002
DATA_FILE_DEFAULT_WIDTH Constant
  Controls how dataset filters are printed by fprintf. Specifies the number of sites per line. Default is 50.
Syntax  DATA_FILE_DEFAULT_WIDTH=value;
Notes
Examples
 Last modified: 5/11/2000
DATA_FILE_PARTITION_MATRIX Constant
  A matrix of partition names and specifications from the most recently read NEXUS data file.
Syntax  DATA_FILE_PARTITION_MATRIX = 2xN string matrix;
Notes DATA_FILE_PARTITION_MATRIX is an 2xN matrix of strings, where N is the number of partitions read from the file (check that the matrix has at least two rows - if not, then no partitions were read). The first row contains the identifier of the partition and the second row contains the partition string, in the same format as the one used by CreatrFilter.
Examples
 Last modified: 8/20/2002
DATA_FILE_PRINT_FORMAT Constant
  Controls how dataset filters are printed by fprintf.
Syntax  DATA_FILE_PRINT_FORMAT=0,1,2 or 3;
Notes
0 (default)- hashmark sequential;
1 - hashmark interleaved;
2 - PHYLIP sequential;
3 - PHYLIP interleaved.
4-7 - NEXUS.

Use ConvertDataFile Standard Tool to change the format of a data file.

Examples
 Last modified: 8/20/2002
DATAFILE_TREE Constant
  Tree string from the most recently read data file.
Syntax  DATAFILE_TREE = Newick tree string;
Notes Check IS_TREE_PRESENT_IN_DATA to verify that there were any trees defined in the data file.
Examples
 Last modified: 8/20/2002
Differentiate Batch language command
  Find analytical derivative of an expression. Supports scalar expressions with +,-,*,/,^, Sin, Cos, Arctan, Log, Exp, Erf, Tan in them; correctly treats variable dependancies. Upon execution 'receptacle' will become a dependent variable, set equal to the derivative expression.
Syntax  Differentiate (receptacle, expression, variable, );
Notes 'receptacle' is the name of the variable to receive the derivative.
'expression' is the expression to differentiate
'variable' is the identifier of the variable with respect to which the derivative should be taken
'times' is an optional parameter of what order derivative should be taken. Default = 1

HyPhy performs only trivial simplifications, so the results of Differentiate may be grossly undersimplified.

Examples
Differentiate (dfx, Exp(x^2),x);

GetString (derivativeStr, dfx, 0); // extract the string of the derivative from dfx

fprintf (stdout, "\n", derivativeStr, "\n");

/* The result is Exp(x^2)*x^2*(2/x) */

 Last modified: 8/20/2002
do..while Batch language command
  The 'do..while'loop. Cond is a logical expression. The loop is executed while Cond evaluates to non-zero.
Syntax  do{..body..}while(Cond);
Notes The brackets must be included in the statement.
Examples
do
{
 i = Random (0,125);
 fprintf (stdout, "\n", i);
}
while ((i>0)&&(i<100));
 Last modified: 8/19/2002
END_OF_FILE Constant
  Is set to 0 or 1 by FSCANF to indicate whether the last read reached the end of file.
Syntax  if (END_OF_FILE){ <...>}else {<...>}
Notes Most useful in a loop, when data is read from the same file to check when to terminate.
Examples
fileName = "list";
while (!END_OF_FILE)
{
    fscanf (fileName,"String", str);
    fprintf (stdout,"\n",str);
}

Simply Reads the file string by string and echoes it to the console.

 Last modified: 8/20/2002
Erf Built-in function
  The error function.
Erf(x)=2/Sqrt(Pi) Integral{0,x,Exp[-t^2]dt}
Syntax  Erf(x)
Notes Works on numbers only. x should be non-negative.
Examples
 Last modified: 8/17/1999
ExecuteCommands Batch language command
  Interpret and execute a sequence of HyPhy batch language commands.
Syntax  ExecuteCommands (commands);
Notes 'commands' is a string (either a literal or a string variable id), containing commands to execute.
Examples
ExecuteCommands("fprintf (stdout, \"\nHello world\n\");");
 Last modified: 8/20/2002
Exp Built-in function
  The exponential function.
Returns both numeric and matrix exponentials.
Syntax  Exp(x)
Notes Works on numbers and square matrices.
Examples
 Last modified: 8/17/1999
FindRoot Batch language command
  Find a root of an equation in a the interval [left_bound, right_bound]. Supports scalar expressions which HyPhy can differentiate. The equation solved is 'expression' = 0. Upon execution 'receptacle' is set to the root, or if no root could be found - to the value of left_bound.
Syntax  FindRoot (receptacle, expression, variable, left_bound, right_bound);
Notes 'receptacle' is the name of the variable to receive the root.
'expression' is the expression to define the equation with. It must be differentiable.
'variable' is the identifier of the variable with respect to which the equation should be solved.
'left_bound', r'ight_bound' define the interval where a root is located. 'right_bound' must be greater than 'left_bound'.

If no (or multiple) roots exist in the interval, 'receptacle' will be set to 'left_bound'.

Examples
FindRoot (root, x^3-2 ,x, 0, 2);
fprintf (stdout, "\nThe real cube root of 2 is:", root, "\n");
 Last modified: 8/19/2002
for Batch language command
  The general 'for' loop construct. Very much like the C 'for'. Init consists of one statement (typically assignment). Cond is a logical statement (compound in general). Incr is the statement executed at the end of each loop iteration.
Syntax  for(Init;Cond;Incr){ ..body..}
Notes Since '++' is not supported, statements like i=i+1 should be used in the Incr part.

Construcr for (..;..;..); is invalid, the {..body..} part must be present.

Examples
for (i=0; i<60; i=i+1)
{
 for(j=i+1;j<61;j=j+1)
 {
  mx[i][j]:=a;
  mx[j][i]:=b;
 }
}
 Last modified: 8/19/2002
FORMAT Data File formatting instruction
  FORMAT is used to indicate what data format a file is in.
Syntax  $FORMAT:"value" (new line char)
Notes This instruction has been deprecated, since HyPhy will autodetect file formats

Allowed values:
PHYLIPS - PHYLIP sequential;
PHYLIPI - PHYLIP interleaved;

Examples
$FORMAT:"PHYLIPS"
 Last modified: 8/20/2002
Format Built-in function
  Format is used to print a floating point number with a specified number of places of precision. The function returns a string containing the appropriate representation of the number. 'width' is the total length of the number string, 'places' is the number of decimal places to be printed. Format (x,width,places) is equivalent to sprintf ("%width.placesf",x);
Syntax  Format (x,width,places);
Notes 'width' should be a non-negative integer. Set width to 0 not to fix the total length.
'places' should be a non-negative integer. Set places to 0 to display the default number of decimal places.
Examples
x = 3.141516;
fprintf (stdout, Format (x,5,2));

// result: " 3.14"

 Last modified: 5/11/2000
fprintf Batch language command
  Output command. Can be used to print essentially any object to a file or to stdout (console).
Syntax  frpintf(filename or stdout or MESSAGE_LOG, list of variables, expressions or string literals);
Notes The first parameter is either a filename, given as a quote-enclosed relative path to the file containing 'fprintf' or stdout (console) w/o the quotes.; also MESSAGE_LOG can be specified as the first argument to direct output to 'messages.log' file. Printing to a file will append rather than rewrite. The variable length list of parameters that follows can contain object identifiers, expressions and quote-enclosed literals. String literals may contain C-style '\code' control sequences, most notably: '\n' for new line and '\t' for tab.

Some objects only print to files due to large sizes. 'filename' could be a string variable.

Examples
x = 12;
fprintf (stdout, x, " squared is ", x^2);
// output:
12 squared is 144

m = {{1,0}{0,1}};
fprintf (stdout, m);
// output
{
{ 1, 0}
{ 0, 1}
}

 Last modified: 8/20/2002
fscanf Batch language command
  Input command. Used to read values of numbers, matrices or trees from files or the console.
Syntax  fscanf(filename or stdin, format string, list of variables expressions or string literals);
Notes The first parameter is either a filename, given as a quote-enclosed relative path to the file containing 'fprintf' or stdin (console) w/o the quotes. It could also be PROMPT_FOR_FILE if the user is to be prompted for the input file. Format string is a quote-enclosed comma separated list with 4 allowed terms:
- Number : read a number;
- Matrix : read a matrix;
- Tree : read a tree
String: read a string.
Fscanf will skip all the characters in between meaningful input.

Matrices are enclosed in '{..}'. Trees are enclosed in '(..)'. 'filename' can be a string variable.

Sets END_OF_FILE.

Examples
// given string:
0.12; {{0,1}{1,0}} sjdiwj ((1,2),3,4)

fscanf (stdin, "Number,Matrix,Tree",x,m,t);

//will read number .12 into x
matrix {{0,1}{1,0}} into m
and tree ((1,2),3,4) into t

 Last modified: 8/20/2002
function Batch language command
  User defined function declaration.
Syntax  function id (param1,param2,...,paramN) {...body...}
Notes param's are passed by value - i.e. changes to parameters within the function will not affect the variables passed as arguments.

To pass parameters by reference use "param&" in function declaration and pass the name of the variable as a string.

Examples
function sqr (by_value)
{
  by_value = by_value * by_value;
  return by_value;
}

function sqr2(by_ref&)
{
  by_ref = by_ref * by_ref;
  return by_ref;
}

x = 2;
y = sqr (x);
fprintf (stdout, x, " ", y, "\n"); /* 2 4, x didn't change*/

y = sqr 2("x"); fprintf (stdout, x, " ", y, "\n"); /* 4 4, x did change*/

 Last modified: 8/19/2002
Gamma Built-in function
  The gamma function.
Gamma[a] = Integral{0,Infinity, Exp[-x] x^(a-1)dx};
Syntax  Gamma(a)
Notes Works on numbers only. 'a' should not be a negative integer.
Examples
 Last modified: 8/17/1999
GammaDist Built-in function
  The gamma distrufunction.
GammaDist[x,a,b] = b^a/Gamma(a) Exp[-bx] x^(a-1).
Syntax  GammaDist(x,a,b)
Notes Works on numbers only. 'a' should not be a negative integer, b should be positive.
Examples
 Last modified: 8/17/1999
GetInformation Batch language command
  GetString is a utility command returns a matrix whose contents vary upon the parameter value.
Syntax  GetInformation (receptacle, object,);
Notes 'receptacle' is the matrix variable to receive the data;
'object' is the object whose information is to be retrieved (currently supports category variables and normal numeric variables)


If 'object' is the name of a numeric variable, 'receptacle' will receive value of the variable
If 'object' is the name of a category numeric variable, 'receptacle' will receive a two column matrix with a row per rate class, with column one containing the rates and column 2 containing the probabilities for the rates.

Examples
 Last modified: 8/19/2002
GetString Batch language command
  GetString is a utility command which returns a string, whose meaning varies, given some object.
Syntax  GetString (receptacle, object, index);
Notes 'receptacle' is the string variable to receive the data;
'object' is the object whose strings are to be retrieved
'index' is the index of the string to be retrieved.

For example, if the object is a data set or a data set filter, the function returns the name of the taxon at i-th position.

If the object is a dependent variable, GetString will return the formula of the dependance.

Additionally, if 'object' is one of the following literals, the following will be returned:
'LikelihoodFunction' - identifier of 'index' likelihood function (use 'rows' command to get the count of all likelihood functions).
'DataSet' - identifier of 'index' data set (use 'rows' command to get the count of all data sets).
'DataSetFilter - identifier of 'index' data set filter (use 'rows' command to get the total count)
'LAST_MODEL_PARAMETER_LIST' - identifier of 'index' parameter of the last defined model (use 'rows' command to get the total count).

Examples
 Last modified: 8/19/2002
GLOBAL_STARTING_POINT Constant
  Specifies the default initial value for all independent variables during optimization. Default is 0.1.
Syntax  GLOBAL_STARTING_POINT=value;
Notes If distance estimates are being used, then the value of GLOBAL_STARTING_POINT is ignored. If GLOBAL_STARTING_POINT is out of bounds for a variable, the closer bound is used as initial value.
Examples
 Last modified: 8/20/2002
>= Operation
  Operation 'greater or equal'.
If x>=y (within floating point precision) returns 1, otherwise returns 0.
Syntax  x>=y
Notes Works on numbers and strings.
Examples
 Last modified: 8/9/2002
> Operation
  Operation 'greater'.
If x>y (within floating point precision) returns 1, otherwise returns 0.
Syntax  x>y
Notes Works on numbers and strings.
Examples
 Last modified: 8/9/2002
HarvestFrequencies Batch language command
  This function allows one to collect the frequencies of characters (states) in a data set (or filter).
Syntax  HarvestFrequencies (receptacle,dataid,atom,unit,position_dependent_flag);
Notes


'receptacle' is the matrix identifier which will refer to the resulting frequencies table.
'dataid' is either a data set or a data set filter.
'atom' determines the size of the data atom to count in terms of character length
'unit' is the size (in terms of character length) of the block within each atom to be counted. The ultimate output will count frequencies of units.
'position_dependent_flag' determines whether units are to be counted accounting for (or not accounting) for their position within the 'atom'.

The resulting matrix will have dimension 'unit states' x 1 (position_dependent_flag is false) or
'unit states' x (atom/unit) (position_dependent_flag is true), where 'unit states' is the number of distinct possible units ordered in terms of the ordering of characters in the data. (e.g. for nucleotides and atom = 3, codon 'cat' will be in row 20.)

dataid must refer to an existing data set. 'atom' and 'unit' are positive integers, and 'atom' must be divisible by 'unit'. 'position_dependent_flag' is either 0 (false) or 1 (true).

Examples
HarvestFrequencies (freq, ds, 1,1,0);

HarvestFrequencies (freq, ds, 3,1,1);

 Last modified: 8/19/2002
IBeta Built-in function
  The incomplete beta function.
IBeta[x,p,q] = Integral{0,x, Gamma[p+q]/Gamma[p]Gamma[q] t^(p-1) (1-t)^(q-1)};
Syntax  IBeta(x,p,q)
Notes Works on numbers only. 'p' and 'q' must be non-negative and x should be in [0,1]
Examples
 Last modified: 6/6/2001
if..then..else Batch language command
  Flow control statement.
Syntax  if (Cond){..body1..} else {..body2..}
Notes Cond is a logical expression. If cond evaluates to non-zero, body1 is executed, otherwise, if body2 is present it is executed (the 'else'clause is optional).

The brackets {} must be included in the statement, even for single statement bodies.

Examples
if (Transition(i,j))
{
 mx[i][j] := transitionRate;
}
else
{
 mx[i][j] := transversionRate;
}
 Last modified: 8/19/2002
IGamma Built-in function
  The incomplete gamma function.
IGamma[a,x] = Integral{0,x, Exp[-t] t^(a-1)dt};
Syntax  IGamma(a,x)
Notes Works on numbers only. 'a' should not be a negative integer and x should be positive.
Examples
 Last modified: 5/10/2000
#include Batch language command
  File inclusion command. The file specified as the argument of the include command is inserted in place of the #include line.
Syntax  #include "filename";
Notes filename must be given relative to the batch file which contains the #include statement.
';' at the end of the command is required.
Examples
#include "Models/F84.def";
 Last modified: 8/17/1999
INTEGRATION_PRECISION_FACTOR Constant
  Designates integration precision used internally for computing cumulative distributions of densities w/o known cumulative distributions formulas. Default is 0.0001.
Syntax  INTEGRATION_PRECISION_FACTOR=value;
Notes
Examples
 Last modified: 8/17/1999
INTERMEDIATE_PRECISION Constant
  Designates intermediate precision for optimization methods that combine gradient ascent and bracketing.
Syntax  INTERMEDIATE_PRECISION=value;
Notes INTERMEDIATE_PRECISION is interpreted as relative precision in the likelihood function values, and when it is reached, optimization routines switch from gradient ascent to bracketing. Default is precision/10 or precision when the max dimension of the model matrix is greater than 21.
Examples
 Last modified: 8/20/2002
InvChi2 Built-in function
  The inverse Chi squared distribution.
InvChi2(r,n) = x, such that P(t<x)=r where t is a random variable distributed as Chi-squared with n degrees of freedom.
Syntax  InvChi2 (x,n)
Notes
Examples
 Last modified: 8/9/2002
Inverse Built-in function
  The matrix inverse function.
Syntax  Inverse(m)
Notes Works on square non-degenerate matrices only.
Examples
The matrix inverse function.
 Last modified: 8/17/1999
IS_TREE_PRESENT_IN_DATA Constant
  Was there a tree defined in the last data file read?
Syntax  IS_TREE_PRESENT_IN_DATA = 0 or 1;
Notes If there was a tree in the data file, DATAFILE_TREE will be set to the tree string. For NEXUS files, which may define multiple trees, also check NEXUS_FILE_TREE_MATRIX.
Examples
 Last modified: 8/20/2002
KEEP_OPTIMAL_ORDER Constant
  When column optimization is active, this boolean constant allows to keep the optimal order between successive optimizations, meaningful when neither the data nor the tree are changed. Default is false.
Syntax  KEEP_OPTIMAL_ORDER=0 or 1;
Notes
Examples
 Last modified: 8/17/1999
LAST_FILE_PATH Constant
  Is set to the last file path returned by a PROMPT_FOR_FILE request. Can be used to access the same file which the user was prompted for at the beginning.
Syntax  
Notes A string variable. Is reset after each call to PROMPT_FOR_FILE. Save in another string variable when working with multiple files.
Examples
 Last modified: 1/19/2000
LF_CALL_COUNT Constant
  Contains the number of likelihood function evaluations up to this point.
Syntax  
Notes
Examples
 Last modified: 8/20/2002
LIKELIHOOD_FUNCTION_OUTPUT Constant
  Controls how likelihood function is printed by fprintf.
Syntax  LIKELIHOOD_FUNCTION_OUTPUT=0,1,2,3,4 or 5;
Notes
0 - print just the likelihood function value;
1 - print the likelihood function value followed by a list of parameter values;
2(default) - print the likelihood function value followed by tree strings with only branch lengths;
3 - print the list of parameters and constraints;
4 -print a list of parameters, with values and constraints as a HyPhy batch language statement. May be useful for saving and restoring parameter estimates.
5 - same as 4, except that all tree declarations are also included.
Examples
 Last modified: 8/21/2002
LikelihoodFunction Batch language command
  The likelihood function construction operation.
Syntax  LikelihoodFunction id = (tree1,datafilterid,...,treen,datafilteridn);
Notes Receives pairs (one or more) of data set filter and tree as arguments.

'id' must be a valid identifier.
'tree' is an existing tree,
'datafilterid' is an existing data set filter.

The number of tips in the tree must be equal to the number of species in the data set filter.

Examples
LikelihoodFunction lf= (tr,df);

LikelihoodFunction lf2= (tr,df,tr2,df2);

 Last modified: 8/19/2002
LIST_ALL_VARIABLES Constant
  Passed as an argument to fprintf produces a list of all currently defined variables.
Syntax  fprintf(destination, LIST_ALL_VARIABLES);
Notes
Examples
 Last modified: 8/17/1999
Log Built-in function
  The natural (base 'eÕ) logarithm function.
Syntax  Log(x)
Notes Works on numbers only. x should be positive.
Examples
 Last modified: 8/17/1999
< Operation
  Operation 'less'.
If x<y (within floating point precision) returns 1, otherwise returns 0.
Syntax  x<y
Notes Works on numbers and strings.
Examples
 Last modified: 8/9/2002
<= Operation
  Operation 'less or equal'.
If x<=y (within floating point precision) returns 1, otherwise returns 0.
Syntax  x<=y
Notes Works on numbers and strings.
Examples
 Last modified: 8/9/2002
LUDecompose Built-in function
  The LU matrix decomposition function.
Any non-degenerate square matrix can be 'uniqely'decomposed into the product of a lower triangular with an upper triangular matrices.
Syntax  LUDecompose(m)
Notes The return value of this function is a Nx(N+1) matrix containing the LU decomposition and the last column keeps track of row interchanges used for pivoting during the decomposition. Used in conjunction with LUSolve.

Works on matrices only. 'm' should be a square matrix.

Examples
 Last modified: 8/20/2002
LUSolve Built-in function
  Solves systems of the form LUx = b. Performs a double back substitution to solve a system of linear equations.
Syntax  LUSolve(m,b)
Notes Argument 'm'is the return value of a call to LUDecompose and 'b'is the right-hand side of the system.

Works on matrices only. 'm' is the matrix returned by LUDecompose and 'b' is a column-vector of matching dimension.
Returns a column-vector containing the solution.

Examples
To solve Ax = b, where A is a non-degenerate square matrix:

m = LUDecompose(A);
x = LUSolve(m,b);

 Last modified: 8/20/2002
Max Built-in function
  Returns the maximum of its arguments.
Syntax  Max(a,b)
Notes Works on numbers only.
Examples
 Last modified: 6/6/2001
MAXIMUM_ITERATIONS_PER_VARIABLE Constant
  If the optimzation precision could not be reached in MAXIMUM_ITERATIONS_PER_VARIABLE*number of independent variables likelihood function evaluations, the routines return with the best value so far. Default is 100.
Syntax  maximumIterationsPerVariable=value;
Notes
Examples
 Last modified: 8/17/1999
MESSAGE_LOG Constant
  The handle to HyPhy messages file which can be passed to fprintf.
Syntax  
Notes
Examples
fprintf (MESSAGE_LOG,"Some message\n");
 Last modified: 8/20/2002
MESSAGE_LOGGING Constant
  Toggles writing messages to file 'messages.log' on and off.
Syntax  LMESSAGE_LOGGING=0 or 1;
Notes Turn message logging off if performing a large number of optimizations in a file.
Examples
 Last modified: 4/12/2000
Min Built-in function
  Returns the minimum of its arguments.
Syntax  Min(a,b)
Notes Works on numbers only.
Examples
 Last modified: 6/6/2001
Model Batch language command
  'Model' is used to define an evolution model by specifying substitution rate matrix and equilibrium frequencies.
Syntax  Model model_name = (rate_matrix_ident,freq_vector_ident,);
Notes Optional boolean mult_flag is used to indicate whether rate matrix elements should be automatically multiplied by the appropriate equilibrium frequency. Default is 1(true), and if the value of the flag is 0 (false), then the equilibrium frequencies should be integrated into the rate matrix explicitly.

Rate matrix must be a square matrix. The diagonal elements are ignored if defined, and reset to ensure reversibility. Frequencies matrix must be a column vector of the same dimension as the rate matrix. The frequency vector must be supplied, even when it is included in the structure of the rate matrix (as in F84).

Examples
See files in the 'Examples' directory.
 Last modified: 8/19/2002
MolecularClock Batch language command
  Molecular clock is called to set additive length constraints on a tree from a node down.
Syntax  MolecularClock (treeid,var1,var2,...,varn);
Notes 'treeid' is either a valid tree identifier (will set MolecularClock on the entire tree), or a node identifier(will set MolecularClock from that node down).

Following 'treeid' is the list of variables to impose the constraint on.

Each node in the part of the tree which MolecularClock is being set on, must depend on the variables in the MolecularClock list.

Examples
m = {{*,a,b,a}{a,*,a,b}{b,a,*,a}{a,b,a,*}};

Tree tr = ((1,2)12,(3,4)34);

MolecularClock (tr,a);

MolecularClock (tr.12,a,b);

 Last modified: 8/19/2002
NEXUS_FILE_TREE_MATRIX Constant
  A matrix of tree strings and identifiers from the most recently read NEXUS data file.
Syntax  NEXUS_FILE_TREE_MATRIX = Nx2 string matrix;
Notes NEXUS_FILE_TREE_MATRIX is an Nx2 matrix of strings, where N is the number of trees read from the file (check IS_TREE_PRESENT_IN_DATA to see if any trees were read at all). The first column contains the identifier of the tree, and the second column contains the actual tree string.
Examples
 Last modified: 8/20/2002
NICETY_LEVEL Constant
  Controls how cpu-time greedy the application is. Default is 1. Maximum(meaningful) value is 6.
Syntax  NICETY_LEVEL=value;
Notes The higher NICETY_LEVEL is, the more processor time will be yielded to other apps. 1 is sufficient for 4x4 models, whereas 3 is appropriate for 61x61 models

HyPhy will now auto-detect the appropriate NICETY_LEVEL to make sure that the interface on MacOS and Windows is responsive.

Has no effect on CLI Unix versions.

Examples
 Last modified: 8/20/2002
OpenDataPanel Batch language command
  This function is used to save and restore states of data panel windows in HyPhy GUI. It is not recommended for direct invokation by the user.
Syntax  OpenDataPanel (dataSetID,"species order","display settings","partition settings"), likefunc ID);
Notes
  • dataSetID: identifier of an existing dataset
  • "species order": a string in the same format used by CreateFilter, used to select what species from dataSetID should be included in the data panel. Leave empty to include all.
  • "display settings": a string, containing 7 comma separated numbers, which control additional features of data display.
    The first number is a flag with the following meaning:
    • Flag has bit 1 turned on (i.e. (flag & 0x01) == 1): show consensus sequence
    • Flag has bit 3 turned on (i.e. (flag & 0x04) == 1): show translated sequence. The index of the sequence to translate is parameter 3 (of 7).
    • Flag has bit 4 turned on (i.e. (flag & 0x08) == 1): show reference sequence. The index of the sequence to translate is parameter 2 (of 7).
  • The fourth number is unused.
  • The fifth number selects the format for sequence names. 0: no names dispayed, 1: first 10 characters displayed, 2: full names displayed.
  • The sixth number selects the format for repeated characters in a site. 0: display actual character, 1: display dots for repeats of the character in sequence 1.
  • The seventh number selects the size of a character group. 9: every 9 sites are grouped (suggested for codon data). 10: every 10 sites are grouped (suggested for nucleotide and aminoacid data).
  • "partition settings": a string containing semicolon separated settings for each partition. Each partition specification is a string with 5 comma separated entries.
    • First entry is the name of the model attached to the partition. "-1" indicates that no model is attached.
    • First entry is the name of the model attached to the partition. "-1" indicates that no model is attached.
    • Second entry selects model options for the partition. Bits 16-19 select parameter options, 0 for local, 1 for global, 2 for global with rate variation, 3 for model specified. Bits 20-23 choose equilibrium frequency options, 0 for partition, 1 for dataset, 2 for equal, 3 for estimate, 4 for model specified. Bits 24-31 specify the number of rate classes, if applicable. Bits 0-15 are not used.
    • Third entry contains partition data settings. The only meaningful value there is the genetic code: bits 16-23 are the internal index of the genetic code table to use.
    • Fourth entry is the RGB color for the partitions: bits 0-7 for blue, 8-15 for green and 16-23 for red.
    • Fifth entry is the identifier of the tree to attach to the partition. "No_tree" specifies that no tree be attached.
  • The last optional parameter is the identifier of the likelihood function to build based on the info provided in other parameters. If the parameter is not included, no LF is built.
Examples
DATA_PANEL_SOURCE_PATH="::data:three.seq";
DataSet three2 = ReadDataFile (DATA_PANEL_SOURCE_PATH);
DataSetFilter beginning = CreateFilter (three2,3,"0-161,165-167","","AGA,AGG,TAA,TAG");
DataSetFilter end = CreateFilter (three2,1,"170-368","");
Tree three_tree2=(a,b,og);
Tree three_tree24=(a,b,og);
OpenDataPanel(three2,"","0,0,0,0,2,0,10", "MG94,65537,720896,14443523,three_tree2;F81,1,0,212,three_tree24", three2_LF);

 Last modified: 8/19/2002
OpenWindow Batch language command
  This command opens windows of HyPhy GUI from batch language files.
Syntax  OpenWindow (window_type, a matrix of parameters);
Notes Refer to the appropriate file in the "Examples" folder of HyPhy distribution for examples. Currently implemented for the Macintosh version of HyPhy ONLY.
Examples
 Last modified: 8/19/2002
OPTIMIZATION_METHOD Constant
  Specifies the optimization method to utilize.
Syntax  OPTIMIZATION_METHOD = value;
Notes Allowed values are:
0 - sequential bracketing;
1 - simplex method (unreliable);
2 - simulated annealing (buggy);
3 - bracketing along gradient directions;
4(default) - gradient ascent followed by sequential bracketing;
5 - bracketing with randomized order of variables;
6 - same as (4) with randomized order of variables during bracketing.
Examples
 Last modified: 8/20/2002
OPTIMIZATION_PRECISION Constant
  Sets the precision goal for optimization routines. Default is 0.001.
Syntax  OPTIMIZATION_PRECSION=value;
Notes
Examples
 Last modified: 1/19/2000
OPTIMIZATION_PRECSION_METHOD Constant
  When OPTIMIZATION_PRECSION_METHOD is 0 (default) the optimization precision objective is applied to the likelihood function value, whereas if it is 1 then all the parameter estimates must meat precision goals.
Syntax  OPTIMIZATION_PRECISION_METHOD=0 or 1;
Notes
Examples
 Last modified: 8/17/1999
Optimize Batch language command
  'Optimize' performs the optimization of the likelihood function.
Syntax  Optimize (receptacle, likelihood_function_id);
Notes 'receptacle' is the identifier of the matrix which receives the results, and 'likelihood_funtion_id' is the likelihood function to be optimized.

Upon completion 'receptacle' will contain 2 rows, the first one listing all the parameters (global, followed by independent, followed by dependent - for order, call frpintf on the likelihood function, with LIKELIHOOD_FUNCTION_OUTPUT = 1); the second row only has 3 entries- the first element is the value of the likelihood function ([1][0]), the second element is the number of independent parameters that were optimized ([1][1]), the third is the number of global(shared) parameters that were optimized([1][2]).

'likelihood_funtion_id' must refer to an existing likelihood function.

Examples
Optimize (res, lf);
 Last modified: 8/19/2002
OPTIMIZE_SUMMATION_ORDER Constant
  When true, pseudo optimal column ordering is used. Default is true.
Syntax  OPTIMIZE_SUMMATION_ORDER=0 or 1;
Notes
Examples
 Last modified: 9/5/2002
OPTIMIZE_SUMMATION_ORDER_PARTITION Constant
  Used when pseudo optimal column ordering is active. Specifies the subpartition size for column ordering.
Syntax  OPTIMIZE_SUMMATION_ORDER_PARTITION=value;
Notes The bigger the value of OPTIMIZE_SUMMATION_ORDER_PARTITION the better savings will be attained, however the time needed for initial column ordering depends quadratically on OPTIMIZE_SUMMATION_ORDER_PARTITION. Default is 750.
Examples
 Last modified: 9/5/2002
Permute Batch language command
  Can be used to create permutations of blocks of columns of 'unit' length of existing data sets or data set filters.
Syntax  DataSetFilter = Permute (datasetid, unit, vertical partition);
Notes datasetid must refer to an existing data set or a data set filter. 'unit' is a positive integer. The last argument is optional.

The specification of vertical partition is identical to that of 'CreateFilter'.

Examples
 Last modified: 8/19/2002
PRINT_DIGITS Constant
  Specifies the number of digits to print for floating point numbers. Default is 8, meaningful values are between 1 and 15.
Syntax  PRINT_DIGITS=value;
Notes A value less than 0 or greater that 15 results in "%f" behaviour, i.e. a maximum possible number of digits.
Examples
 Last modified: 8/20/2002
PSTreeString Built-in function
  Returns a string containing a post script rendering of the tree. The length of the branches can be scaled on any model parameter (if it is defined for all branches), or left unscaled (all branches have equal length). The command also takes a page size parameter.
Syntax  res = PSTreeString(tree_ident, parameter_name, page_size);
Notes 'parameter_name' must be either an empty string (branches have equal lengths) or a parameter name (e.g. "mu"), if that parameter is defined for every branch. Two special values are also allowed:
- "EXPECTED_NUMBER_OF_SUBSTITUTIONS" scales the tree on the expected number of substitution per site, assuming there is a model attached to every branch of the tree;
- "STRING_SUPPLIED_LENGTHS" scales the tree on the lengths provided in the Newick string itself (assuming there are some).

The page size parameter is a 1x2 matrix which defines the width (first entry) and the height (second entry) of the page in points. 1 point = 1/72 of an inch. If page_size = {{0,0}}, the size of the page is set to 8x11 inches (US Letter size).

The output of the command is PostScript code which should be saved to a file and later rendered by a PS viewer program or sent to a PS printer.

Examples
Tree tr = ((1,2),3,4);
pString = PSTreeString (tr,"",{{200,200}});
fprintf ("outfile.ps",pString);
 Last modified: 8/14/2002
Random Built-in function
  The random number generation function.
Returns a random number of from a uniform distribution over [a,b].

Syntax  Random(a,b);
Notes
Examples
 Last modified: 8/17/1999
RANDOM_SEED Constant
  RANDOM_SEED is set to the seed fed to the standard random number generator seed function.
Syntax  RANDOM_SEED
Notes
Examples
 Last modified: 8/17/1999
RANDOM_STARTING_PERTURBATIONS Constant
  Used in conjunction with GLOBAL_STARTING_POINT if small (10% in magnitude) random perturbations are desired. Default value is false(0).
Syntax  RANDOM_STARTING_PERTURBATIONS = 0 or 1;
Notes
Examples
 Last modified: 8/17/1999
ReadDataFile Batch language command
  Data file reading instruction.
Syntax  DataSet datasetid = ReadDataFile("filename");
Notes The argument of the command designates the file to be read. The resulting data set is stored in the receptacle 'datasetid'. Upon successful completion of this command, 'datasetid' contains the data, and 3 variables are automatically created:
- datasetid.species : number of species in the data set
- datasetid.sites: number of sites(columns) in the data set
- datasetid.unique_sites: number of unique sites in the data set.

If 'filename' is set to 'PROMPT_FOR_FILE', the user will be asked to specify the data file name at the time of execution.

filename must be given relative to the batch file which contains the ReadDataFile statement.
datasetid is a valid identifier (alphanumeric sequence with possible underscores beginning with a letter or an underscore).

Sets IS_TREE_PRESENT_IN_DATA, DATAFILE_TREE, NEXUS_FILE_TREE_MATRIX (for NEXUS files), DATA_FILE_PARTITION_MATRIX.

Examples
DataSet ds = ReadDataFile("../data/hiv.dat");
 Last modified: 8/20/2002
ReconstructAncestors Batch language command
  Reconstructs the list of ancestral sequences based on current parameter values. The sequences are reconstructed by finding the states of internal tree nodes which maximize the likelihood of the tree.
Syntax  DataSet datasetid = ReconstrucAncestors(likelihood_function_id);
Notes Will work only for models without rate heterogeneity.

datasetid is a valid identifier (alphanumeric sequence with possible underscores beginning with a letter or an underscore).
likelihood_function_id must reference an already defined likelihood function.

Examples
DataSet ds = ReconstructAncestors (likFunc);
 Last modified: 8/19/2002
RELATIVE_PRECISION Constant
  When RELATIVE_PRECISION is true, the optimization routines use relative error to determine when to return. Default is false.
Syntax  RELATIVE_PRECISION=0 or 1;
Notes
Examples
 Last modified: 8/17/1999
REPEAT Data File formatting instruction
  REPEAT denotes the repeat character in interleaved data files.
Syntax  $REPEAT:"repeat char" (new line char)
Notes A repeat character is used when the 2nd or later species has the same data at a site, as the first species. Note that '.'is automatically a repeat character.

Does not apply to NEXUS files.

Examples
$REPEAT:"-"

$REPEAT:""
(do not use Ô.Õ as repeat)

 Last modified: 8/20/2002
ReplicateConstraint Batch language command
  ReplicateConstraint exists to facilitate defining tree (or subtree) wide constraints. It allows to replicate a single constraint throughout the matching parts of a tree or several trees.
Syntax  ReplicateConstraint ("constraint", argument_1, ..., argument_N);
Notes 'constraint' is a quotation-enclosed HyPhy expression, with several special properies:
  • "thisK" (K is a number starting at 1) will be replaced with argument_K. Therefore the number of arguments must match the number of different "thisK" in the expression.
  • '?' will be match any substring
. 'argument_K' is a tree or a tree node.
Examples
See examples in 'Examples/ConstraintDefinition'.
 Last modified: 8/19/2002
RerootTree Built-in function
  Returns a string containing the Newick style string of the tree rerooted at a specified branch.
Syntax  res = RerootTree(tree_ident, branch_name);
res = RerootTree (string_ident, 0 - unused 2nd parameter);
Notes Can also be used to generate "balanced" tree strings, i.e. reroot a tree in such a way as to balance the number of nodes in each subtree. The latter functionality is useful for speeding up calculations on unrooted trees.

'branch_name' must be a valid tip or internal node name (a string), obtained by a call to 'TipName' or 'BranchName'. The call makes sense if the original tree was rooted.

"string_ident" must be a valid Newick tree string.

Examples
Tree tr = (((a,b),c,d);
newTr = RerootTree (tr, "b");

Result: (b,((c,d),a));

unbalanced_tree = "(1,(2,(3,(4,(5,(6,7))))))"; rebalanced_tree = RerootTree (unbalanced_tree,0);

// rebalanced_tree is now "((5,(6,7)),(1,(2,(3,4))))"

 Last modified: 8/20/2002
return Batch language command
  The 'return' statement for user functions.
Syntax  return object;
Notes return must be followed by an object (a constant, variable or formula).
Examples
 Last modified: 8/17/1999
Rows Built-in function
  The number of rows function.
Returns the number of rows in a matrix.
Can also be used to count the number of objects of a given kind.
Syntax  Rows(m)
Notes m must be a matrix.

Rows can also be used to count objects of a certain type (an ugly hack indeed!)
Rows("LikelihoodFunction") returns the number of currently defined likelihood functions
Rows("DataSet") returns the number of currently defined datasets.
Rows("DataSetFilter") returns the number of currently defined dataset filters.
Rows("Variable") returns the number of currently defined variables
Rows("LAST_MODEL_PARAMETER_LIST") returns the number of parameters in the last defined model.

Examples
 Last modified: 8/9/2002
SCREEN_HEIGHT Constant
  The height in pixels of the display.
Syntax  
Notes Used in OpenWindow. Currently only available in MacOS.
Examples
 Last modified: 8/20/2002
SCREEN_WIDTH Constant
  The width in pixels of the display.
Syntax  
Notes Used in OpenWindow. Currently only available in MacOS.
Examples
 Last modified: 8/20/2002
SelectTemplateModel Batch language command
  Prompts the user to select a template model appropriate for the data contained in 'filterid'.
Syntax  SelectTemplateModel(filterid);
Notes 'filterid' must be an existing data set filter.
Examples
SetDialogPrompt ("Please specify a data file:");
DataSet ds = ReadDataFile(PROMPT_FOR_FILE);
DataSetFilter filteredData = CreateFilter (ds,1);
SelectTemplateModel(filteredData);
 Last modified: 5/11/2000
SetDialogPrompt Batch language command
  Used to set the prompt string presented to the user when PROMPT_FOR_STRING or PROMPT_FOR_FILE is used.
Syntax  SetDialogPrompt("string");
Notes Prompt string must be less than 255 characters.
Examples
 Last modified: 8/17/1999
SetParameter Batch language command
  SetParameter is used to assign a value to independent parameters of the likelihood function.
Syntax  SetParameter (likfuncID, parameterIndex, newValue);
Notes 'likefuncID' is the identifier of an existing likelihood function;
'parameterIndex' is an integer index (starting at 0) of the parameter to assign the value to;
'newValue' is the value to assign
Examples
SetParameter (lf,0,.12345);
SetParameter (lf,index,someMatrix[index]);
 Last modified: 5/11/2000
SimulateDataSet Batch language command
  Data file simulation instruction.
Syntax  DataSet datasetid = SimulateDataSet(likelihood_function_id, "comma separated list of excluded states",simulated rates, category variable names);
Notes The first argument of the call is an existing likelihood function. 'Simulate' uses current values of parameters in the function to simulate a data set of the same size/type as the one references by the function. If the likelihood function references more than one data set, 'SimulateDataSet' will work with the first data set reference, and all others which have the same number of species/type. The second optional parameter is the list of states which are not permissible as the result of simulation. Whatever states are included there will not be present in the simulated data. 'datasetid' received the simulated data.

'simulated_rates' (optional) - a matrix to receive simulated heterogeneous rates. The dimension of the matrix will be KxN, where K is the number of category variables that the likelihood function depends; N is the total number of data sites in the likelihood function. The entries in a column of the matrix will be the (randomly sampled) category variables that the site depends on.

'category_variable_names' (optional) - a string matrix, of dimension Kx1. The entry in row 'i' is the name of the i-th category variable. Used in conjunction with 'simulated_rates'.

datasetid is a valid identifier (alphanumeric sequence with possible underscores beginning with a letter or an underscore).
likelihood_function_id must reference an already defined likelihood function.

Examples
DataSet sds = SimulateDataSet(lf);

or

DataSet sds = SimulateDataSet(lf,"TAA,TGA,TAG");

 Last modified: 8/22/2002
Sin Built-in function
  The sine function.
Syntax  Sin(x)
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
SKIP_OMISSIONS Constant
  When true, any data sites which contain characters w/o information (deletions) are omitted from the dataset filters. Default is false.
Syntax  SKIP_OMISSIONS=0 or 1;
Notes
Examples
 Last modified: 8/17/1999
Sqrt Built-in function
  The square root function.
Syntax  Sin(x)
Notes Works on numbers only. 'x' should be non-negative.
Examples
 Last modified: 8/17/1999
Tan Built-in function
  The tangent function.
Syntax  Tan(x)
Notes Works on numbers only.
Examples
 Last modified: 8/17/1999
TEXTreeString Built-in function
  Returns a string containing a LaTEX picture description of the tree. The length of the branches can be scaled on any model parameter (if it is defined for all branches), or left unscaled (all branches have equal length).
Syntax  res = TEXTreeString(tree_ident, parameter_name);
Notes 'parameter_name' must be either an empty string (branches have equal lengths) or a parameter name (e.g. "mu"), if that parameter is defined for every branch. Two special values are also allowed:
- "EXPECTED_NUMBER_OF_SUBSTITUTIONS" scales the tree on the expected number of substitution per site, assuming there is a model attached to every branch of the tree;
- "STRING_SUPPLIED_LENGTHS" scales the tree on the lengths provided in the Newick string itself (assuming there are some).

The output of the command is LaTEX code which should be saved to a file and later rendered by a LaTEX program.

Examples
 Last modified: 8/14/2002
Time Built-in function
  The timer function.
Returns the value of the system timer in seconds.
Syntax  Time(0)
Notes
Examples
To measure how long an operation takes:

timer = Time(0);
....do smth here...
timer = Time(0)-timer;

Now timer contains the number of seconds that the operation took.

 Last modified: 5/11/2000
TipCount Built-in function
  When applied to a tree variable, returns the number of tips(leaves) in the tree.
Syntax  res = TipCount(tree_ident);
Notes
Examples
 Last modified: 1/19/2000
TipName Built-in function
  Returns a string containing the name of a tip of the tree.
Syntax  res = TipName(tree_ident, tip_index);
Notes Valid index range is 0 to TipCount (tree_ident)-1. The name of the tip is of the form 'Tip1' rather than 'Tree.Tip1'.
Examples
Tree tr = ((a,b),c,d);
tName = TipName (tr, 2);

Result: "c".

 Last modified: 5/11/2000
TOKEN Data File formatting instruction
  TOKEN sets up translation relations between characters.
Syntax  $TOKEN:"new char"=ÓmeaningÓ (new line char)
Notes Note: this is NOT case sensitive. A new character can be anything, whereas the meaning is defined in terms of base set chars.

Does not apply to NEXUS files.

Examples
$TOKEN:"B" = "CGT"
B is either C, G or T)
 Last modified: 8/20/2002
Transpose Built-in function
  The matrix transpose function.
Returns the transpose of a matrix.
Syntax  Transpose(m)
Notes 'm' must be a matrix.
Examples
 Last modified: 8/17/1999
Tree Batch language command
  Tree construction command.
Syntax  Tree treeid = tree string;
Notes Tree string is a in a parenthetical form (Newick format), with the following extensions:
- internal nodes can be named by placing the name after ')' which closes the block of children of the internal node.
- each node may have its own model matrix. To attach a matrix to a node place '{matrix name}' after the name of the node.

By default, each node will be associated with the last defined matrix.

If tree string is set to 'PROMPT_FOR_STRING', the user will be prompted to enter the string.

Node names must be alphanumeric ('_' is allowed).
Rooted trees will be automatically 'unrooted'.
One branch trees are allowed.

Examples
Tree tr = ((1,2),3,4);

Tree tr = ((1{M},2{M})Internal{M},3,(4,5));

 Last modified: 8/19/2002
USE_DISTANCES Constant
  When true (default) distance methods are used (when possible) to get intial parameter value.
Syntax  USE_DISTANCES=0 or 1;
Notes
Examples
 Last modified: 8/17/1999
UseModel Batch language command
  Used to select a model to be attached to branches of trees subsequently.
Syntax  UseModel (model_name);
Notes 'model_name' must be a valid model defined previously with the 'Model' command., or USE_NO_MODEL to reset the model used by default.
Examples
See files in the 'Examples' directory.
 Last modified: 8/19/2002
while Batch language command
  The 'while'loop.
Syntax  while(cond){..body..}
Notes Cond is a logical expression. The loop is executed while Cond evaluates to non-zero.

The brackets {}must be included in the statement, even for single-statement bodies.

Examples
while ((i>0)&&(i>100))
{
 i = Random (0,125);
 fprintf (stdout, "\n", i);
}
 Last modified: 8/19/2002
ZCDF Built-in function
  Cumulative distribution function of the standard normal random variable
ZCDF(x) = P{N(0,1)<x}
Syntax  ZCDF (x)
Notes 'x' must be a number.
Examples
ZCDF(0) returns 0.5
 Last modified: 8/9/2002

 
Sergei L. Kosakovsky Pond and Spencer V. Muse, 1997-2002