cpw {ComPairWise}R Documentation

Compare alternate alignments of phylogenetic or population genetic data

Description

cpw is the main (outer) function of ComPairWise. It takes 2 or more DNA/RNA alignment files and compares them, column by column. It outputs information about which columns are identical and which aren't.

Usage

cpw(name1 = "", name2 = "", ref = "", n = 2, out = "screen", outfile = "", graph = "screen", gr.file = "", pairwise = TRUE, onegraph = TRUE, nexus.out = TRUE, keep = FALSE, gap = "-", miss = "?", ...)

Arguments

name1 String. Name of the first alignment
name2 String. Name of the second alignment
ref Integer or string. Which alignment should be treated as the reference?
n Integer. How many alignments?
out String. Where should the text output go?
outfile String. What should the output file (if any) be named?
graph String or FALSE. Where should graphics output go?
gr.file String. What should the graphics output file (if any) be named?
pairwise Logical. If n > 2, do you want pairwise comparisons or a single group comparison of alignments?
onegraph Logical. If n > 2 and pairwise = TRUE, do you want graphical output on one graph or multiple graphs?
nexus.out Logical. Do you want a NEXUS-format sets block of identical and different columns?
keep Logical. Should R do a global assignment of certain variables, thus leaving them in the workspace after the function is done?
gap String. What is the gap character?
miss String. What is the missing data character?
... Currently does nothing

Details

cpw is the function implementing ComPairWise, pairwise or group comparison of alternative alignments of a give DNA/RNA sequence data set. The method is described in Roberts & Olson.

Command-line options have been designed so that users with no R experience should be able to get the output they want easily.

Some options do interact, and the program will ignore conflicting instructions if necessary.

A more complete description of the options and arguments:

name1, name2
Default: "". If left blank (the default), the program will prompt for these later. For repetitive or batch runs, they can be specified here.

They can be either valid filenames, or the names (as strings) of R objects of class alignment, e.g. those created by a call to read.alignment. Objects and filenames can be freely mixed.

ref
Default: "". If an integer, the index of the alignment to treat as the reference, e.g. 1 for the first alignment. If a string, the name of the alignment to treat as the reference. If this is left blank (the default) the program will prompt for it later on; if nothing is entered at the prompt, it will use the longest alignment as the reference.
n
Default: 2. How many alignments are being compared?
out
Default: "screen". Valid options are "screen", "file", and "" (no text output). Interacts with outfile, and will be automatically set to "file" if outfile is given. If out = "file" and outfile = "", the filename will be "compairwise.out".
outfile
Default: "". Name of file for text output. Interacts with out; if outfile is specified, it will force output to go to a file no matter what was specified for out. This often means that only one or the other needs to be set.
graph
Default: "screen". Valid options are "screen", "" or "none" or FALSE (for no graphing), and options for various types of files: "jpeg", "jpg", "ps", "postscript", "eps", "png", "bmp", "pdf". graph = "screen" will make R open one or more graphics devices (depending on pairwise and onegraph). For file output it will open a graphics device depending on the file type desired. File types not supported by your version of R will, obviously, not work; similarly, it would be wise to set graph = "" on a system that doesn't support graphics at all.

gr.file
Default: "". Base filename for graphics output, if /option{graph} is set to send graphics to a file. A file extension (which depends on the file type) will be appended to this. If onegraph = FALSE and multiple graphs are generated, the indices of the alignments in each comparison will also be appended.
pairwise
Default: TRUE. If n > 2, you have three options for how to do comparisons, depending on the settings for ref and pairwise. If pairwise = FALSE, cpw will do only a group comparison to determine which columns are identical in all alignments. If pairwise = TRUE, it will do all (n * (n - 1))/2 pairwise comparisons if no reference alignment is specified, or all n - 1 comparisons to the reference alignment if one is specified. If pairwise = TRUE, onegraph controls whether you get one graph or many.
onegraph
Default: TRUE. If multiple comparisons are being done, should graphical output all be on one graph, or separate graphs?
nexus.out
Default: TRUE. Should the text output include a NEXUS-format sets block with a character set for identical and non-identical columns?
keep
Default: FALSE. If keep = TRUE, cpw will make global assignments of some variables with the <<- operator, thus leaving them in the workspace after the function exits. Advanced R users might want to use this option for further analysis of their alignments. However, many of the same objects can be kept by assigning the value of the function cpw() instead, and this is a better way if all you want is summary information.
gap
Default: "-". A string (one or more values) telling cpw what values indicate an alignment gap. Any non-base character is acceptable.
miss
Default: "?". A string (one or more values) telling cpw what values indicate missing data. Any non-base character is acceptable. Note however that "N" is treated as an ambiguous base and should not be used for missing data, which is treated quite differently!
...
Currently does nothing.

cpw implements the alignment comparison described in ComPairWise. For every column of a reference alignment, it determines whether an identically-aligned column exists in an alternate alignment.

As well as the value (which is returned invisibly if no assignment is being made), the program will print some text output to the screen or a file (or neither), and will make a sketchy graph of the results to the screen or a file (or neither).

Value

A list, returned invisibly if no assignment is being made. For each comparison that was done:

totals Summary list:
cols_align...
Number of columns in each alignment
cols_compared
Number of columns compared (depends on ref)
n_ident
Number of columns that were identical
n_diff
Number of columns that were different
n_gap_miss
Number of columns that were all gap/missing
diff Indices of columns that were different
ident Indices of columns that were identical
lab String of +,-,o for identical, different, and all gap/missing columns, respectively
id.num Numeric vector of 1 for identical columns, 0 for different, NA for all gap/missing
id.log Logical vector of TRUE for identical columns, FALSE for different, NA for all gap/missing

Author(s)

Trina E. Roberts, trina.roberts@uaf.edu

References

Roberts, T.E. and L.E. Olson. ComPairWise...

Examples


#The simplest case: 2 alignments, no options changed:
#The example below sets the working directory so it can find the example files

## Not run: 
       
oldwd <- getwd()
setwd(file.path(.Library, "ComPairWise", "examples"))
cpw("sample.nex", "sample2.nex")
setwd(oldwd)
rm(oldwd)
## End(Not run)

[Package ComPairWise version 1.01 Index]