
                                  fpenny 



Wiki

   The master copies of EMBOSS documentation are available at
   http://emboss.open-bio.org/wiki/Appdocs on the EMBOSS Wiki.

   Please help by correcting and extending the Wiki pages.

Function

   Penny algorithm, branch-and-bound

Description

   Finds all most parsimonious phylogenies for discrete-character data
   with two states, for the Wagner, Camin-Sokal, and mixed parsimony
   criteria using the branch-and-bound method of exact search. May be
   impractical (depending on the data) for more than 10-11 species.

Algorithm

   PENNY is a program that will find all of the most parsimonious trees
   implied by your data. It does so not by examining all possible trees,
   but by using the more sophisticated "branch and bound" algorithm, a
   standard computer science search strategy first applied to
   phylogenetic inference by Hendy and Penny (1982). (J. S. Farris
   [personal communication, 1975] had also suggested that this strategy,
   which is well-known in computer science, might be applied to
   phylogenies, but he did not publish this suggestion).

   There is, however, a price to be paid for the certainty that one has
   found all members of the set of most parsimonious trees. The problem
   of finding these has been shown (Graham and Foulds, 1982; Day, 1983)
   to be NP-complete, which is equivalent to saying that there is no fast
   algorithm that is guaranteed to solve the problem in all cases (for a
   discussion of NP-completeness, see the Scientific American article by
   Lewis and Papadimitriou, 1978). The result is that this program,
   despite its algorithmic sophistication, is VERY SLOW.

   The program should be slower than the other tree-building programs in
   the package, but useable up to about ten species. Above this it will
   bog down rapidly, but exactly when depends on the data and on how much
   computer time you have (it may be more effective in the hands of
   someone who can let a microcomputer grind all night than for someone
   who has the "benefit" of paying for time on the campus mainframe
   computer). IT IS VERY IMPORTANT FOR YOU TO GET A FEEL FOR HOW LONG THE
   PROGRAM WILL TAKE ON YOUR DATA. This can be done by running it on
   subsets of the species, increasing the number of species in the run
   until you either are able to treat the full data set or know that the
   program will take unacceptably long on it. (Making a plot of the
   logarithm of run time against species number may help to project run
   times).

  The Algorithm

   The search strategy used by PENNY starts by making a tree consisting
   of the first two species (the first three if the tree is to be
   unrooted). Then it tries to add the next species in all possible
   places (there are three of these). For each of the resulting trees it
   evaluates the number of steps. It adds the next species to each of
   these, again in all possible spaces. If this process would continue it
   would simply generate all possible trees, of which there are a very
   large number even when the number of species is moderate (34,459,425
   with 10 species). Actually it does not do this, because the trees are
   generated in a particular order and some of them are never generated.

   Actually the order in which trees are generated is not quite as
   implied above, but is a "depth-first search". This means that first
   one adds the third species in the first possible place, then the
   fourth species in its first possible place, then the fifth and so on
   until the first possible tree has been produced. Its number of steps
   is evaluated. Then one "backtracks" by trying the alternative
   placements of the last species. When these are exhausted one tries the
   next placement of the next-to-last species. The order of placement in
   a depth-first search is like this for a four-species case (parentheses
   enclose monophyletic groups):

     Make tree of first two species     (A,B)
          Add C in first place     ((A,B),C)
               Add D in first place     (((A,D),B),C)
               Add D in second place     ((A,(B,D)),C)
               Add D in third place     (((A,B),D),C)
               Add D in fourth place     ((A,B),(C,D))
               Add D in fifth place     (((A,B),C),D)
          Add C in second place: ((A,C),B)
               Add D in first place     (((A,D),C),B)
               Add D in second place     ((A,(C,D)),B)
               Add D in third place     (((A,C),D),B)
               Add D in fourth place     ((A,C),(B,D))
               Add D in fifth place     (((A,C),B),D)
          Add C in third place     (A,(B,C))
               Add D in first place     ((A,D),(B,C))
               Add D in second place     (A,((B,D),C))
               Add D in third place     (A,(B,(C,D)))
               Add D in fourth place     (A,((B,C),D))
               Add D in fifth place     ((A,(B,C)),D)

   Among these fifteen trees you will find all of the four-species rooted
   bifurcating trees, each exactly once (the parentheses each enclose a
   monophyletic group). As displayed above, the backtracking depth-first
   search algorithm is just another way of producing all possible trees
   one at a time. The branch and bound algorithm consists of this with
   one change. As each tree is constructed, including the partial trees
   such as (A,(B,C)), its number of steps is evaluated. In addition a
   prediction is made as to how many steps will be added, at a minimum,
   as further species are added.

   This is done by counting how many binary characters which are
   invariant in the data up the species most recently added will
   ultimately show variation when further species are added. Thus if 20
   characters vary among species A, B, and C and their root, and if tree
   ((A,C),B) requires 24 steps, then if there are 8 more characters which
   will be seen to vary when species D is added, we can immediately say
   that no matter how we add D, the resulting tree can have no less than
   24 + 8 = 32 steps. The point of all this is that if a previously-found
   tree such as ((A,B),(C,D)) required only 30 steps, then we know that
   there is no point in even trying to add D to ((A,C),B). We have
   computed the bound that enables us to cut off a whole line of inquiry
   (in this case five trees) and avoid going down that particular branch
   any farther.

   The branch-and-bound algorithm thus allows us to find all most
   parsimonious trees without generating all possible trees. How much of
   a saving this is depends strongly on the data. For very clean (nearly
   "Hennigian") data, it saves much time, but on very messy data it will
   still take a very long time.

   The algorithm in the program differs from the one outlined here in
   some essential details: it investigates possibilities in the order of
   their apparent promise. This applies to the order of addition of
   species, and to the places where they are added to the tree. After the
   first two-species tree is constructed, the program tries adding each
   of the remaining species in turn, each in the best possible place it
   can find. Whichever of those species adds (at a minimum) the most
   additional steps is taken to be the one to be added next to the tree.
   When it is added, it is added in turn to places which cause the fewest
   additional steps to be added. This sounds a bit complex, but it is
   done with the intention of eliminating regions of the search of all
   possible trees as soon as possible, and lowering the bound on tree
   length as quickly as possible.

   The program keeps a list of all the most parsimonious trees found so
   far. Whenever it finds one that has fewer steps than these, it clears
   out the list and restarts the list with that tree. In the process the
   bound tightens and fewer possibilities need be investigated. At the
   end the list contains all the shortest trees. These are then printed
   out. It should be mentioned that the program CLIQUE for finding all
   largest cliques also works by branch-and-bound. Both problems are
   NP-complete but for some reason CLIQUE runs far faster. Although their
   worst-case behavior is bad for both programs, those worst cases occur
   far more frequently in parsimony problems than in compatibility
   problems.

  Controlling Run Times

   Among the quantities available to be set at the beginning of a run of
   PENNY, two (howoften and howmany) are of particular importance. As
   PENNY goes along it will keep count of how many trees it has examined.
   Suppose that howoften is 100 and howmany is 1000, the default
   settings. Every time 100 trees have been examined, PENNY will print
   out a line saying how many multiples of 100 trees have now been
   examined, how many steps the most parsimonious tree found so far has,
   how many trees of with that number of steps have been found, and a
   very rough estimate of what fraction of all trees have been looked at
   so far.

   When the number of these multiples printed out reaches the number
   howmany (say 1000), the whole algorithm aborts and prints out that it
   has not found all most parsimonious trees, but prints out what is has
   got so far anyway. These trees need not be any of the most
   parsimonious trees: they are simply the most parsimonious ones found
   so far. By setting the product (howoften times howmany) large you can
   make the algorithm less likely to abort, but then you risk getting
   bogged down in a gigantic computation. You should adjust these
   constants so that the program cannot go beyond examining the number of
   trees you are reasonably willing to wait for. In their initial setting
   the program will abort after looking at 100,000 trees. Obviously you
   may want to adjust howoften in order to get more or fewer lines of
   intermediate notice of how many trees have been looked at so far. Of
   course, in small cases you may never even reach the first multiple of
   howoften and nothing will be printed out except some headings and then
   the final trees.

   The indication of the approximate percentage of trees searched so far
   will be helpful in judging how much farther you would have to go to
   get the full search. Actually, since that fraction is the fraction of
   the set of all possible trees searched or ruled out so far, and since
   the search becomes progressively more efficient, the approximate
   fraction printed out will usually be an underestimate of how far along
   the program is, sometimes a serious underestimate.

   A constant that affects the result is "maxtrees", which controls the
   maximum number of trees that can be stored. Thus if "maxtrees" is 25,
   and 32 most parsimonious trees are found, only the first 25 of these
   are stored and printed out. If "maxtrees" is increased, the program
   does not run any slower but requires a little more intermediate
   storage space. I recommend that "maxtrees" be kept as large as you
   can, provided you are willing to look at an output with that many
   trees on it! Initially, "maxtrees" is set to 100 in the distribution
   copy.

  Methods and Options

   The counting of the length of trees is done by an algorithm nearly
   identical to the corresponding algorithms in MIX, and thus the
   remainder of this document will be nearly identical to the MIX
   document. MIX is a general parsimony program which carries out the
   Wagner and Camin-Sokal parsimony methods in mixture, where each
   character can have its method specified. The program defaults to
   carrying out Wagner parsimony.

   The Camin-Sokal parsimony method explains the data by assuming that
   changes 0 --> 1 are allowed but not changes 1 --> 0. Wagner parsimony
   allows both kinds of changes. (This under the assumption that 0 is the
   ancestral state, though the program allows reassignment of the
   ancestral state, in which case we must reverse the state numbers 0 and
   1 throughout this discussion). The criterion is to find the tree which
   requires the minimum number of changes. The Camin-Sokal method is due
   to Camin and Sokal (1965) and the Wagner method to Eck and Dayhoff
   (1966) and to Kluge and Farris (1969).

   Here are the assumptions of these two methods:
    1. Ancestral states are known (Camin-Sokal) or unknown (Wagner).
    2. Different characters evolve independently.
    3. Different lineages evolve independently.
    4. Changes 0 --> 1 are much more probable than changes 1 --> 0
       (Camin-Sokal) or equally probable (Wagner).
    5. Both of these kinds of changes are a priori improbable over the
       evolutionary time spans involved in the differentiation of the
       group in question.
    6. Other kinds of evolutionary event such as retention of
       polymorphism are far less probable than 0 --> 1 changes.
    7. Rates of evolution in different lineages are sufficiently low that
       two changes in a long segment of the tree are far less probable
       than one change in a short segment.

   That these are the assumptions of parsimony methods has been
   documented in a series of papers of mine: (1973a, 1978b, 1979, 1981b,
   1983b, 1988b). For an opposing view arguing that the parsimony methods
   make no substantive assumptions such as these, see the papers by
   Farris (1983) and Sober (1983a, 1983b), but also read the exchange
   between Felsenstein and Sober (1986).

Usage

   Here is a sample session with fpenny


% fpenny 
Penny algorithm, branch-and-bound
Phylip character discrete states file: penny.dat
Phylip penny program output file [penny.fpenny]: 


How many
trees looked                                       Approximate
at so far      Length of        How many           percentage
(multiples     shortest tree    trees this long    searched
of  100):      found so far     found so far       so far
----------     ------------     ------------       ------------
     1           8.00000                1                6.67
     2           8.00000                3               20.00
     3           8.00000                3               53.33
     4           8.00000                3               93.33

Output written to file "penny.fpenny"

Trees also written onto file "penny.treefile"


   Go to the input files for this example
   Go to the output files for this example

Command line arguments

   Standard (Mandatory) qualifiers:
  [-infile]            discretestates File containing one or more data sets
  [-outfile]           outfile    [*.fpenny] Phylip penny program output file

   Additional (Optional) qualifiers (* if not always prompted):
   -weights            properties Phylip weights file (optional)
   -ancfile            properties Phylip ancestral states file (optional)
   -mixfile            properties Phylip mix output file (optional)
   -method             menu       [Wagner] Choose the method to use (Values:
                                  Wag (Wagner); Cam (Camin-Sokal); Mix
                                  (Mixed))
   -outgrno            integer    [0] Species number to use as outgroup
                                  (Integer 0 or more)
   -howmany            integer    [1000] How many groups of trees (Any integer
                                  value)
   -howoften           integer    [100] How often to report, in trees (Any
                                  integer value)
   -simple             boolean    Branch and bound is simple
   -threshold          float      [$(infile.discretesize)] Threshold value
                                  (Number 1.000 or more)
   -[no]trout          toggle     [Y] Write out trees to tree file
*  -outtreefile        outfile    [*.fpenny] Phylip tree output file
                                  (optional)
   -printdata          boolean    [N] Print data at start of run
   -[no]progress       boolean    [Y] Print indications of progress of run
   -[no]treeprint      boolean    [Y] Print out tree
   -stepbox            boolean    [N] Print out steps in each site
   -ancseq             boolean    [N] Print states at all nodes of tree

   Advanced (Unprompted) qualifiers: (none)
   Associated qualifiers:

   "-outfile" associated qualifiers
   -odirectory2        string     Output directory

   "-outtreefile" associated qualifiers
   -odirectory         string     Output directory

   General qualifiers:
   -auto               boolean    Turn off prompts
   -stdout             boolean    Write first file to standard output
   -filter             boolean    Read first file from standard input, write
                                  first file to standard output
   -options            boolean    Prompt for standard and additional values
   -debug              boolean    Write debug output to program.dbg
   -verbose            boolean    Report some/full command line options
   -help               boolean    Report command line options. More
                                  information on associated and general
                                  qualifiers can be found with -help -verbose
   -warning            boolean    Report warnings
   -error              boolean    Report errors
   -fatal              boolean    Report fatal errors
   -die                boolean    Report dying program messages

Input file format

   fpenny reads discrste character data.

  (0,1) Discrete character data

   These programs are intended for the use of morphological systematists
   who are dealing with discrete characters, or by molecular
   evolutionists dealing with presence-absence data on restriction sites.
   One of the programs (PARS) allows multistate characters, with up to 8
   states, plus the unknown state symbol "?". For the others, the
   characters are assumed to be coded into a series of (0,1) two-state
   characters. For most of the programs there are two other states
   possible, "P", which stands for the state of Polymorphism for both
   states (0 and 1), and "?", which stands for the state of ignorance: it
   is the state "unknown", or "does not apply". The state "P" can also be
   denoted by "B", for "both".

   There is a method invented by Sokal and Sneath (1963) for linear
   sequences of character states, and fully developed for branching
   sequences of character states by Kluge and Farris (1969) for recoding
   a multistate character into a series of two-state (0,1) characters.
   Suppose we had a character with four states whose character-state tree
   had the rooted form:

               1 ---> 0 ---> 2
                      |
                      |
                      V
                      3

   so that 1 is the ancestral state and 0, 2 and 3 derived states. We can
   represent this as three two-state characters:

                Old State           New States
                --- -----           --- ------
                    0                  001
                    1                  000
                    2                  011
                    3                  101

   The three new states correspond to the three arrows in the above
   character state tree. Possession of one of the new states corresponds
   to whether or not the old state had that arrow in its ancestry. Thus
   the first new state corresponds to the bottommost arrow, which only
   state 3 has in its ancestry, the second state to the rightmost of the
   top arrows, and the third state to the leftmost top arrow. This coding
   will guarantee that the number of times that states arise on the tree
   (in programs MIX, MOVE, PENNY and BOOT) or the number of polymorphic
   states in a tree segment (in the Polymorphism option of DOLLOP,
   DOLMOVE, DOLPENNY and DOLBOOT) will correctly correspond to what would
   have been the case had our programs been able to take multistate
   characters into account. Although I have shown the above character
   state tree as rooted, the recoding method works equally well on
   unrooted multistate characters as long as the connections between the
   states are known and contain no loops.

   However, in the default option of programs DOLLOP, DOLMOVE, DOLPENNY
   and DOLBOOT the multistate recoding does not necessarily work
   properly, as it may lead the program to reconstruct nonexistent state
   combinations such as 010. An example of this problem is given in my
   paper on alternative phylogenetic methods (1979).

   If you have multistate character data where the states are connected
   in a branching "character state tree" you may want to do the binary
   recoding yourself. Thanks to Christopher Meacham, the package contains
   a program, FACTOR, which will do the recoding itself. For details see
   the documentation file for FACTOR.

   We now also have the program PARS, which can do parsimony for
   unordered character states.

  Input files for usage example

  File: penny.dat

    7    6
Alpha1    110110
Alpha2    110110
Beta1     110000
Beta2     110000
Gamma1    100110
Delta     001001
Epsilon   001110

Output file format

   fpenny output is standard: a set of trees, which will be printed as
   rooted or unrooted depending on which is appropriate, and if the user
   elects to see them, tables of the number of changes of state required
   in each character. If the Wagner option is in force for a character,
   it may not be possible to unambiguously locate the places on the tree
   where the changes occur, as there may be multiple possibilities. A
   table is available to be printed out after each tree, showing for each
   branch whether there are known to be changes in the branch, and what
   the states are inferred to have been at the top end of the branch. If
   the inferred state is a "?" there will be multiple
   equally-parsimonious assignments of states; the user must work these
   out for themselves by hand.

   If the Camin-Sokal parsimony method (option C or S) is invoked and the
   A option is also used, then the program will infer, for any character
   whose ancestral state is unknown ("?") whether the ancestral state 0
   or 1 will give the fewest state changes. If these are tied, then it
   may not be possible for the program to infer the state in the internal
   nodes, and these will all be printed as ".". If this has happened and
   you want to know more about the states at the internal nodes, you will
   find helpful to use MOVE to display the tree and examine its interior
   states, as the algorithm in MOVE shows all that can be known in this
   case about the interior states, including where there is and is not
   amibiguity. The algorithm in PENNY gives up more easily on displaying
   these states.

   If the A option is not used, then the program will assume 0 as the
   ancestral state for those characters following the Camin-Sokal method,
   and will assume that the ancestral state is unknown for those
   characters following Wagner parsimony. If any characters have unknown
   ancestral states, and if the resulting tree is rooted (even by
   outgroup), a table will be printed out showing the best guesses of
   which are the ancestral states in each character. You will find it
   useful to understand the difference between the Camin-Sokal parsimony
   criterion with unknown ancestral state and the Wagner parsimony
   criterion.

   If option 6 is left in its default state the trees found will be
   written to a tree file, so that they are available to be used in other
   programs. If the program finds multiple trees tied for best, all of
   these are written out onto the output tree file. Each is followed by a
   numerical weight in square brackets (such as [0.25000]). This is
   needed when we use the trees to make a consensus tree of the results
   of bootstrapping or jackknifing, to avoid overrepresenting replicates
   that find many tied trees.

  Output files for usage example

  File: penny.fpenny


Penny algorithm, version 3.68
 branch-and-bound to find all most parsimonious trees

Wagner parsimony method




requires a total of              8.000

    3 trees in all found




  +-----------------Alpha1
  !
  !        +--------Alpha2
--1        !
  !  +-----4     +--Epsilon
  !  !     !  +--6
  !  !     +--5  +--Delta
  +--2        !
     !        +-----Gamma1
     !
     !           +--Beta2
     +-----------3
                 +--Beta1

  remember: this is an unrooted tree!




  +-----------------Alpha1
  !
--1  +--------------Alpha2
  !  !
  !  !           +--Epsilon
  +--2        +--6
     !  +-----5  +--Delta
     !  !     !
     +--4     +-----Gamma1
        !
        !        +--Beta2
        +--------3
                 +--Beta1

  remember: this is an unrooted tree!




  +-----------------Alpha1
  !
  !           +-----Alpha2
--1  +--------2
  !  !        !  +--Beta2
  !  !        +--3
  +--4           +--Beta1
     !
     !           +--Epsilon
     !        +--6
     +--------5  +--Delta
              !
              +-----Gamma1

  remember: this is an unrooted tree!

  File: penny.treefile

(Alpha1,((Alpha2,((Epsilon,Delta),Gamma1)),(Beta2,Beta1)))[0.3333];
(Alpha1,(Alpha2,(((Epsilon,Delta),Gamma1),(Beta2,Beta1))))[0.3333];
(Alpha1,((Alpha2,(Beta2,Beta1)),((Epsilon,Delta),Gamma1)))[0.3333];

Data files

   None

Notes

   None.

References

   None.

Warnings

   None.

Diagnostic Error Messages

   None.

Exit status

   It always exits with status 0.

Known bugs

   None.

See also

                    Program name                Description
                    eclique      Largest clique program
                    edollop      Dollo and polymorphism parsimony algorithm
                    edolpenny    Penny algorithm Dollo or polymorphism
                    efactor      Multistate to binary recoding program
                    emix         Mixed parsimony algorithm
                    epenny       Penny algorithm, branch-and-bound
                    fclique      Largest clique program
                    fdollop      Dollo and polymorphism parsimony algorithm
                    fdolpenny    Penny algorithm Dollo or polymorphism
                    ffactor      Multistate to binary recoding program
                    fmix         Mixed parsimony algorithm
                    fmove        Interactive mixed method parsimony
                    fpars        Discrete character parsimony

Author(s)

                    This program is an EMBOSS conversion of a program written by Joe
                    Felsenstein as part of his PHYLIP package.

                    Although we take every care to ensure that the results of the EMBOSS
                    version are identical to those from the original package, we recommend
                    that you check your inputs give the same results in both versions
                    before publication.

                    Please report all bugs in the EMBOSS version to the EMBOSS bug team,
                    not to the original author.

History

                    Written (2004) - Joe Felsenstein, University of Washington.

                    Converted (August 2004) to an EMBASSY program by the EMBOSS team.

Target users

                    This program is intended to be used by everyone and everything, from
                    naive users to embedded scripts.
