minCharChange: Estimating the Minimum Number of Character Transitions Using Maximum Parsimony

Description

minCharChange is a function which takes a cladogram and a discrete trait and finds the solutions of inferred character states for ancestral nodes that minimizes the number of character state transitions (either gains or losses/reversals) for a given topology and a set of discrete character data. minCharChange relies on ancPropStateMat, which is a wrapper for phangorn's function ancestral.pars.

Usage

minCharChange(trait, tree, randomMax = 10000, maxParsimony = TRUE,
  orderedChar = FALSE, type = "MPR", cost = NULL, printMinResult = TRUE)

ancPropStateMat(trait, tree, orderedChar = FALSE, type = "MPR",
  cost = NULL)

Arguments

trait

A vector of trait values for a discrete character, preferably named with taxon names identical to the tip labels on the input tree.

tree

A cladogram of type 'phylo'. Any branch lengths are ignored.

randomMax

The maximum number of cladograms examined when searching a large number of solutions consistent with the reconstructed ancestral states from ancestral.pars with the minimum number of character state transitions. If the number of potential s

maxParsimony

If maxParsimony is TRUE (the default) then only solutions with the smallest number of total transitions examined will be returned. Note that since solutions are stochastically 'guessed' at, and the number of possible solutions may not be exhaustively se

orderedChar

If TRUE (not the default), then the character will be reconstructed with a cost (step) matrix of a linear, ordered character. This is not applicable if type = "ACCTRAN", as cost matrices cannot be used with ACCTRAN in ancestral.pars

type

The parsimony algorithm applied by ancestral.pars, which can apply one of two:
"MPR" (the default) is a relatively fast algorithm developed by Hamazawa et al. (1995) and Narushima
and Hanazawa (1997), which relies on reconstructing the stat

cost

A matrix of the cost (i.e. number of steps) necessary to change between states of the input
character trait. If NULL (the
default), the character is assumed to be unordered with equal cost to change from any state to another.
Cost matrices only impact

printMinResult

If TRUE (the default), a summary of the results is printed to the terminal. The
information in this summary may be more detailed if the results of the analysis are simpler (i.e.
fewer unique solutions).

`Value`

A list is invisibly returned containing the following elements:

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

`Details`

The wrapper function ancPropStateMat simply automates the application of functions
ancestral.pars and phyDat from phangorn, along with several additional checks
and code to present the result as a matrix, rather than a specialized list.

Note that although the default orderedChar argument assumes that multistate characters are unordered,
the results of character change will always be reported as gains and losses relative to the numbering of the
states in the output transitionSumChanges, exactly as if they had been ordered. In the case
where the character is actually ordered, this may be
considered a conservative approach, as using a parsimony algorithm for unordered character states allows fewer
gains or losses to be counted on branches where multiple gains and losses are reported. If the character is
presumably unordered and multistate, however, then the gains and losses division
is arbitrary nonsense and should be combined to
to obtain the total number of character changes.

`References`

Hanazawa, M., H. Narushima, and N. Minaka. 1995. Generating most parsimonious reconstructions on
a tree: A generalization of the Farris-Swofford-Maddison method. Discrete Applied Mathematics
56(2-3):245-265.

Narushima, H., and M. Hanazawa. 1997. A more efficient algorithm for MPR problems in phylogeny.
Discrete Applied Mathematics 80(2-3):231-238.

Schliep, K. P. 2011. phangorn: phylogenetic analysis in R. Bioinformatics 27(4):592-593.

Swofford, D. L., and W. P. Maddison. 1987. Reconstructing ancestral character states under
Wagner parsimony. Mathematical Biosciences 87(2):199-229.

`See Also`

The functions described here are effectively wrapers of phangorn's function
ancestral.pars.

`Examples`

Run this code# let's write a quick & dirty ancestral trait plotting function

quickAncPlotter<-function(tree,ancData,cex){
	ancCol<-(1:ncol(ancData))+1
	plot(tree,show.tip.label=FALSE,no.margin=TRUE,direction="upwards")
	tiplabels(pch=16,pie=ancData[(1:Ntip(tree)),],cex=cex,piecol=ancCol,
		col=0)
	nodelabels(pie=ancData[-(1:Ntip(tree)),],cex=cex,piecol=ancCol)
	}

# example with retiolitid graptolite data

data(retiolitinae)

#unordered, MPR
ancMPR<-ancPropStateMat(retioTree, trait=retioChar[,2], type="MPR")
#unordered, ACCTRAN
ancACCTRAN<-ancPropStateMat(retioTree, trait=retioChar[,2], type="ACCTRAN")

#let's compare MPR versus ACCTRAN results
layout(1:2)
quickAncPlotter(retioTree,ancMPR,cex=0.5)
text(x=4,y=5,"type='MPR'",cex=1.5)
quickAncPlotter(retioTree,ancACCTRAN,cex=0.5)
text(x=5,y=5,"type='ACCTRAN'",cex=1.5)

minCharChange(retioTree,trait=retioChar[,2],type="MPR")
minCharChange(retioTree,trait=retioChar[,2],type="ACCTRAN")

# with simulated data

set.seed(444)
tree<-rtree(50)
#simulate under a likelihood model
char<-rTraitDisc(tree,k=3,rate=0.7)
tree$edge.length<-NULL
tree<-ladderize(tree)

#unordered, MPR
ancMPR<-ancPropStateMat(tree, trait=char, type="MPR")
#unordered, ACCTRAN
ancACCTRAN<-ancPropStateMat(tree, trait=char, type="ACCTRAN")
#ordered, MPR
ancMPRord<-ancPropStateMat(tree, trait=char, orderedChar=TRUE, type="MPR")

#let's compare MPR versus ACCTRAN results
layout(1:2)
quickAncPlotter(tree,ancMPR,cex=0.3)
text(x=8,y=15,"type='MPR'",cex=1.5)
quickAncPlotter(tree,ancACCTRAN,cex=0.3)
text(x=9,y=15,"type='ACCTRAN'",cex=1.5)
#MPR has much more uncertainty in node estimates
	#but that doesn't mean ACCTRAN is preferable

#let's compare unordered versus ordered under MPR
layout(1:2)
quickAncPlotter(tree,ancMPR,cex=0.3)
text(x=8,y=15,"ordered char",cex=1.5)
quickAncPlotter(tree,ancMPRord,cex=0.3)
text(x=9,y=15,"ordered char'",cex=1.5)
layout(1)

# what ancPropStateMat automates (with lots of checks):

require(phangorn)

char1<-matrix(char,,1)
rownames(char1)<-names(char)
#translate into something for phangorn to read
char1<-phyDat(char1,type="USER",levels=sort(unique(char1)))
x<-ancestral.pars(tree,char1,type="MPR")
y<-ancestral.pars(tree,char1,type="ACCTRAN")

#estimating minimum number of transitions with MPR
minCharChange(tree,trait=char,type="MPR")

#and now with ACCTRAN
minCharChange(tree,trait=char,type="ACCTRAN")
Run the code above in your browser using DataLab