Understanding outputs

The results table

HomoplasyFinder will generate a file called consistencyIndexReport_[DATE].txt, containing the following table:

Position	ConsistencyIndex	CountsACGT	MinimumNumberChangesOnTree
57	0.5	0:0:139:16	2
179	0.5	0:151:0:4	2
207	0.5	5:0:150:0	2
241	0.5	6:149:0:0	2
339	0.5	0:0:4:151	2
534	0.5	152:0:0:3	2
559	0.5	0:0:2:153	2
689	0.5	16:139:0:0	2
696	0.5	5:150:0:0	2
771	0.5	0:6:0:149	2

The above table provides details for each of the sites in the nucleotide alignment provided that were found to be inconsistent with the phylogeny provided. Here's a description of each column:

1. Position - a 1-indexed position in the nucleotide alignment provided

2. ConsistencyIndex - the consistency index of the current site. Here's how to calculate the index.

3. CountsACGT - a ":" delimited set of counts for the number of times each nucleotide (A-Adenine, C-Cytosine, G-Guanine, and T-Thymine) were found at the current position

4. MinimumNumberChangesOnTree - the minimum number of nucleotide changes required to occur along the branches of the phylogenetic tree provided to explain the pattern of nucleotides observed at the current position

Importantly, to retain all consistent positions in the results table use the ---includeConsistent flag in the command line or the includeConsistentSitesInReport parameter in either of the runHomoplasyFinderJarTool() or runHomoplasyFinderInJava() functions in R.

To read in the results table into R, use the following code:

# Note the directory where HomoplasyFinder was executed
workingDirectory <- "/home/josephcrispell/Desktop/"

# Note the date the results table was created by HomoplasyFinder
date <- "30-10-18" # Format: "%d-%m-%y"
  
# Read in the output table
resultsFile <- paste0(workingDirectory, "consistencyIndexReport_", date, ".txt")
results <- read.table(resultsFile, header=TRUE, sep="\t", stringsAsFactors=FALSE)

---

The output FASTA file

HomoplasyFinder will, if requested using the ---createFasta flag in the command line, or the createFasta paramater in the R functions above, create an output FASTA file. The output FASTA file will be almost identical to the input FASTA file provided but any inconsistent sites identified will have been removed.

---

The annotated newick tree file

HomoplasyFinder will, if requested using the ---createAnnotatedTree flag in the command line, or the createAnnotatedNewickTree paramater in the R functions, create an annotated Newick formatted phylogenetic tree file. Each node in the phylogeny contains "-" delimited set of inconsistent positions, if a change was necessary at that node to explain the nucleotides present for a inconsistent position. Otherwise, the annotated tree file will be identical to the input phylogenetic tree file. Use the following command in R to view this tree:

# Note the FASTA file that was used with HomoplasyFinder
fastaFile <- "example.fasta"

# Read in the annotated tree file
tree <- readAnnotatedTree(workingDirectory, date)

# Plot the annotated tree
plotAnnotatedTree(tree, results[results$Position < 1, "Position"], fastaFile)

As a standard Newick formatted tree file, the annotated phylogenetic tree produced by HomoplasyFinder is compatible with most phylogenetic tree viewing platforms - for example are readily figtree and icytree able to view the annotated trees.