
                                 fdolpenny 



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 Dollo or polymorphism

Description

   Finds all most parsimonious phylogenies for discrete-character data
   with two states, for the Dollo or polymorphism 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

   DOLPENNY is a program that will find all of the most parsimonious
   trees implied by your data when the Dollo or polymorphism parsimony
   criteria are employed. 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 DOLPENNY 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 losses. 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 losses (or retentions of
   polymorphism) is evaluated.

   The point of this is that if a previously-found tree such as
   ((A,B),(C,D)) required fewer losses, 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 losses 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
   DOLPENNY, two (howoften and howmany) are of particular importance. As
   DOLPENNY goes along it will keep count of how many trees it has
   examined. Suppose that howoften is 100 and howmany is 300, the default
   settings. Every time 100 trees have been examined, DOLPENNY 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 X 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 pay for (or 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 DOLLOP, and thus the
   remainder of this document will be nearly identical to the DOLLOP
   document. The Dollo parsimony method was first suggested in print in
   verbal form by Le Quesne (1974) and was first well-specified by Farris
   (1977). The method is named after Louis Dollo since he was one of the
   first to assert that in evolution it is harder to gain a complex
   feature than to lose it. The algorithm explains the presence of the
   state 1 by allowing up to one forward change 0-->1 and as many
   reversions 1-->0 as are necessary to explain the pattern of states
   seen. The program attempts to minimize the number of 1-->0 reversions
   necessary.

   The assumptions of this method are in effect:
    1. We know which state is the ancestral one (state 0).
    2. The characters are evolving independently.
    3. Different lineages evolve independently.
    4. The probability of a forward change (0-->1) is small over the
       evolutionary times involved.
    5. The probability of a reversion (1-->0) is also small, but still
       far larger than the probability of a forward change, so that many
       reversions are easier to envisage than even one extra forward
       change.
    6. Retention of polymorphism for both states (0 and 1) is highly
       improbable.
    7. The lengths of the segments of the true tree are not so unequal
       that two changes in a long segment are as probable as one in a
       short segment.

   That these are the assumptions is established in several of my papers
   (1973a, 1978b, 1979, 1981b, 1983). 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).

   One problem can arise when using additive binary recoding to represent
   a multistate character as a series of two-state characters. Unlike the
   Camin-Sokal, Wagner, and Polymorphism methods, the Dollo method can
   reconstruct ancestral states which do not exist. An example is given
   in my 1979 paper. It will be necessary to check the output to make
   sure that this has not occurred.

   The polymorphism parsimony method was first used by me, and the
   results published (without a clear specification of the method) by
   Inger (1967). The method was published by Farris (1978a) and by me
   (1979). The method assumes that we can explain the pattern of states
   by no more than one origination (0-->1) of state 1, followed by
   retention of polymorphism along as many segments of the tree as are
   necessary, followed by loss of state 0 or of state 1 where necessary.
   The program tries to minimize the total number of polymorphic
   characters, where each polymorphism is counted once for each segment
   of the tree in which it is retained.

   The assumptions of the polymorphism parsimony method are in effect:
    1. The ancestral state (state 0) is known in each character.
    2. The characters are evolving independently of each other.
    3. Different lineages are evolving independently.
    4. Forward change (0-->1) is highly improbable over the length of
       time involved in the evolution of the group.
    5. Retention of polymorphism is also improbable, but far more
       probable that forward change, so that we can more easily envisage
       much polymorhism than even one additional forward change.
    6. Once state 1 is reached, reoccurrence of state 0 is very
       improbable, much less probable than multiple retentions of
       polymorphism.
    7. The lengths of segments in the true tree are not so unequal that
       we can more easily envisage retention events occurring in both of
       two long segments than one retention 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 fdolpenny


% fdolpenny 
Penny algorithm Dollo or polymorphism
Phylip character discrete states file: dolpenny.dat
Phylip dolpenny program output file [dolpenny.fdolpenny]: 


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           3.00000                1                0.95

Output written to file "dolpenny.fdolpenny"

Trees also written onto file "dolpenny.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    [*.fdolpenny] Phylip dolpenny program output
                                  file

   Additional (Optional) qualifiers (* if not always prompted):
   -weights            properties Weights file
   -ancfile            properties Ancestral states file
   -thresh             toggle     [N] Use threshold parsimony
*  -threshold          float      [1] Threshold value (Number 0.000 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)
   -[no]simple         boolean    [Y] Branch and bound is simple
   -method             menu       [d] Parsimony method (Values: d (Dollo); p
                                  (Polymorphism))
   -[no]trout          toggle     [Y] Write out trees to tree file
*  -outtreefile        outfile    [*.fdolpenny] 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
   -ancseq             boolean    [N] Print states at all nodes of tree
   -stepbox            boolean    [N] Print out steps in each character

   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

   fdolpenny reads discrete character data with "?", "P", "B" states
   allowed. .

  (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: dolpenny.dat

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

Output file format

   fdolpenny output format is standard. It includes a rooted tree and, if
   the user selects option 4, a table of the numbers of reversions or
   retentions of polymorphism necessary in each character. If any of the
   ancestral states has been specified to be unknown, a table of
   reconstructed ancestral states is also provided. When reconstructing
   the placement of forward changes and reversions under the Dollo
   method, keep in mind that each polymorphic state in the input data
   will require one "last minute" reversion. This is included in the
   tabulated counts. Thus if we have both states 0 and 1 at a tip of the
   tree the program will assume that the lineage had state 1 up to the
   last minute, and then state 0 arose in that population by reversion,
   without loss of state 1.

   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 A option is used, then the program will infer, for any
   character whose ancestral state is unknown ("?") whether the ancestral
   state 0 or 1 will give the best tree. 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 DOLMOVE to display the tree and examine its
   interior states, as the algorithm in DOLMOVE shows all that can be
   known in this case about the interior states, including where there is
   and is not amibiguity. The algorithm in DOLPENNY gives up more easily
   on displaying these states.

   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: dolpenny.fdolpenny


Penny algorithm for Dollo or polymorphism parsimony, version 3.68
 branch-and-bound to find all most parsimonious trees


requires a total of              3.000

    3 trees in all found




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





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





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


  File: dolpenny.treefile

(Delta,(Epsilon,(Gamma1,(Alpha2,((Beta2,Beta1),Alpha1)))))[0.3333];
(Delta,(Epsilon,(Gamma1,((Beta2,Beta1),(Alpha2,Alpha1)))))[0.3333];
(Delta,(Epsilon,(Gamma1,(((Beta2,Beta1),Alpha2),Alpha1))))[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
                    ffactor      Multistate to binary recoding program
                    fmix         Mixed parsimony algorithm
                    fmove        Interactive mixed method parsimony
                    fpars        Discrete character parsimony
                    fpenny       Penny algorithm, branch-and-bound

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.
