+
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
Last modified: 8/9/2002 |