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, name2Default: "". 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.
refDefault: "". 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.
nDefault: 2. How many alignments are being compared?
outDefault: "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".
outfileDefault: "". 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.
graphDefault: "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.fileDefault: "". 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.
pairwiseDefault: 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.
onegraphDefault: TRUE. If multiple comparisons are being done, should graphical output all be on one graph, or separate graphs?
nexus.outDefault: TRUE. Should the text output include a NEXUS-format sets block with a character set for identical and non-identical columns?
keepDefault: 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.
gapDefault: "-". A string (one or more values) telling cpw what values indicate an alignment gap. Any non-base character is acceptable.
missDefault: "?". 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_comparedNumber of columns compared (depends on ref)
n_identNumber of columns that were identical
n_diffNumber of columns that were different
n_gap_missNumber 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]