fastdnaml_scripts.txt

fastDNAml is an attempt to solve the same problem as DNAML, but to do so faster and using less memo

initially placing a new sequence in the growing tree (but does not change the
time required to subsequently test rearrangements).  This will probably become
the default program behavior in the near future.

Any possible downside of the quickadd option would be a decreased frequency of
finding the globally optimal tree.  Since you should NEVER depend on a single
order of addition yielding the best tree, multiple jumble runs will still be
the best way to check the reproducibility of any presumptively optimal tree.
Quickadd should let you do this more quickly!


RESTART (R)

  Format:  restart  checkpoint_file_name
  Example: quickadd <archaea.phylip | restart checkpoint.13728 | fastDNAml

Adds a restart option and appends the last tree in the checkpoint file to the
input.  This conflicts with a usertree option.  Note that this script makes a
valiant attempt to figure out the beginning location of the last tree in the
file.  In particular, you should not modify lines in the checkpoint file (or
any other treefile that you supply) so that they end with a semicolon or a
period (other than the final line of a tree).  The example will continue
building a tree for the archaea.phylip data from whereever the checkpoint
file left off.


TRANSITION-TRANSVERSION RATIO (T)

  Format:  transition  ratio_value
  Example: transition 2.0 <archaea.phylip | global 4 | fastDNAml

Adds the transition-transversion option and appropriate auxiliary data line
to the input.  This option with a value of 2.0 (the program's default value)
can be used before a global or treefile option with auxiliary data (see the
example).


TREEFILE (Y)

  Format:  treefile  [format_number]

Adds the treefile option, and, if requested, the treefile format auxiliary
data line to the input data.  In this latter case, it is essential that the
input contain (or the treefile command be preceded by) a B, J or T option.
The only formats at present are 1 (default Newick format) and 2 (a prolog
phylip_tree fact).

  Example: outgroup 5 <archaea.phylip | treefile | fastDNAml > archaea.out
  Example: transition 2.0 <archaea.phylip | treefile 2 | fastDNAml

The first example will infer a tree for the archaea data, root it on sequence
5, and write a tree to treefile.PID, where PID is a number (the process ID of
fastDNAml).  The second example writes a prolog fact for the tree inferred from
these same data.  The transition/transversion ratio is supplied with its
default value, only so that the treefile format will be found in the input file.


USERLENGTHS (L)

  Format:  userlengths
  Example: usertree archaea.tree <archaea.phylip | userlengths | fastDNAml

Adds the userlengths option to the input.  This must be used in conjunction
with the usertree option, so it is usually easier to add the second parameter
to the usertree script (see below).  This script is useful if the usertree is
already part of the input, and you only need to alter the lengths option.


USERTREE (U)

  Format: usertree  tree_file [ L ]

Adds the usertree option and appends the tree count and all of the trees in
the named file to the input.  If the L parameter is included, it is added to
the options line to invoke the program userlengths option.

  Example: usertree archaea.tree <archaea.phylip | userlengths | fastDNAml
  Example  usertree archaea.tree L <archaea.phylip | fastDNAml

These two examples are equivalent.

All of the trees in the file are added, so this is not an appropriate way to
evaluate the last tree in a checkpoint file.  Restart is the script to use for
that latter task.


WEIGHTS (W)

  Format:  weights  weight_data_file
  Example: weights  archaea.weight <archaea.phylip | fastDNAml

Adds the weights option (W) and the corresponding data to the input.  The data
must have the format specified for PHYLIP dnaml 3.3.  The first line must be
the word Weights and AT LEAST 3 BLANK SPACES, followed by one weight value per
sequence position.  The weights 0 - 35 are represented by the series 0, 1, 2,
3, ..., 8, 9, A, B, C, ..., Y, Z.  These latter data can be on one or more
lines.  For example,

  Weights     111111111111001100000100011111100000000000000110000110000000
              111101111111111111111111011100000111001011100000000011


WEIGHTS and CATEGORIES (W C)

  Format: weights_categories  weight_and_category_data_file

Adds both the userweights and categories options to the input, along with the
weights and categories data in the named file.  This is useful for importing
the data from the DNArates program into fastDNAml.  The format of the data
file should conform to that of weights auxiliary data followed by categories
auxiliary data.  As noted for the categories option above, in order to
generate output compatible with PHYLIP dnaml, this should be the first option
added (so that the categories data are inserted immediately before the
sequence data).




              SCRIPTS THAT PERFORM OTHER USEFUL FUNCTIONS



clean_checkpoints

Usage:  clean_checkpoints

Locates checkpoint files for which there is a corresponding treefile, and
deletes the former.  This is useful in cleaning up the directory when the
treefile option is in use.



clean_jumbles

Usage:  clean_jumbles  [ -nosummary ]  file_name_root

Finds all files with the form "file_name_root.PID", where PID is the process
ID appended by fastDNAml_boot and fastDNAml_loop to results from analyses with
different jumble seeds.  Unless the nosummary flag is included, all likelihoods
are summarized in a file named "file_name_root.summary".  The likelihoods are
screened for the best value.  An output file with the optimal score is renamed
to "file_name_root.out", and the corresponding treefile (if any) is renamed
"file_name_root.tree".  All other treefiles and output files matching the name
are deleted.  Corresponding checkpoint files are also deleted.



fastDNAml_boot

Usage:  fastDNAml_boot [-seed seed]  [-boots nboot] \
                       [-max maxjumble]  [-nice nicevalue]  [-noclean] \
                       in_file  n_best  [ "dnaml_opt1 [ | dnaml_opt2 ... ]" ]

For the current bootstrap seed, the sequence input order is jumbled (up to
maxjumble times) until the same best tree is found n_best times.  The output
files are then reduced to a summary of the scores produced by jumbling, and one
example of the best tree.  The number process is then repeated with new
bootstrap seeds until nboot samples have been analyzed.

Boot, jumble, treefile and quickadd are included by the script and should not
be specified by the user or in the data file.  Additional爁astDNAml
program options are enclosed in quotes, and separated by vertical bars (|).

Flags and parameters:

  in_file         -- name of the input data file
  n_best          -- input order is jumbled (up to maxjumble times) until
                     same tree is found n_best times
  -boots nboot    -- number of different bootstrap samples (Default=1)
  -seed seed      -- seed for first bootstrap (Default is based on the process
                     ID and time of day)
  -max maxjumble  -- maximum attempts at replicating inferred tree
                     (Default=10)
  -nice nicevalue -- run fastDNAml with specified nice value (Default=10)
  -noclean        -- inhibits cleanup of the output files for the individual
                     seeds

Example:

  fastDNAml_boot -boots 100 -seed 137 -max 8 -nice 20  test_data.phylip  2



fastDNAml_loop

Usage:  fastDNAml_loop [-max maxjumble]  [-nice nicevalue]  [-noclean] \
                       in_file  n_best  [ "dnaml_opt1 [ | dnaml_opt2 ... ]" ]

For the given input file, the sequence input order is jumbled (up to maxjumble
times) until the same best tree is found n_best times.  The output files are
then reduced to a summary of the scores produced by jumbling, and one example
of the best tree.

Jumble, treefile and quickadd are included by the script and should not
be specified by the user or in the data file.  Additional爁astDNAml
program options are enclosed in quotes, and separated by vertical bars (|).

Flags and parameters:

  in_file         -- name of the input data file
  n_best          -- input order is jumbled (up to maxjumble times) until
                     same tree is found n_best times
  -max maxjumble  -- maximum attempts at replicating inferred tree
                     (Default=10)
  -nice nicevalue -- run fastDNAml with specified nice value (Default=10)
  -noclean        -- inhibits cleanup of the output files for the individual
                     seeds

Example:

  fastDNAml_loop -max 15 -nice 20  test_data.phylip  3



out.PID

Usage:  out.PID  program  outfile
   or   out.PID  -o outfile  program  program_args

When a process sends its output to standard out, this script puts it in a
file whose name is the outfile.PID, where outfile is the name given by the
user and PID is the process ID of the running program.  This is useful when
a program is run a number of times, and output needs to be put in different
files.  Since the fastDNAml program uses the PID in generating the checkpoint
file name and the tree file name, it is useful to be able to put the program
output itself in a file with the corresponding suffix.



scores

Usage:  scores  files

Extracts and sorts likelihood values from fastDNAml output files.  The
corresponding file names are also provided.



trees2NEXUS

Usage:  trees2NEXUS  [ treefile ... ]

Concatenate Newick format trees from named file(s) or from standard input
into a single file suitable for the PAUP (tested) or MacClade (untested)
programs.  For example, it is possible to combine trees from bootstrap
replicates in order to use the PAUP concensus tree functions.



trees2prolog

Usage:  trees2prolog  [ treefile ... ]

Accepts Newick format trees from named file(s) or from standard input and
as converts them to prolog facts of the form pseudoNewick(Comment, Tree).
Each tree must be entirely on one line, and they must be similar to the
form produced by the fastDNAml program.  In particular, the only permitted
comment is one preceeding the whole tree.  If there is no leading commment,
then the fact produced will have arity 1.