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:

\item

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.

\item

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.

\item

nDefault: 2. How many alignments are being compared?

\item

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".

\item

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.

\item

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.

\item

gr.fileDefault: "". Base filename for graphics output, if /optiongraph 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.

\item

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.

\item

onegraphDefault: TRUE. If multiple comparisons are being done, should graphical output all be on one graph, or separate graphs?

\item

nexus.outDefault: TRUE. Should the text output include a NEXUS-format sets block with a character set for identical and non-identical columns?

\item

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.

\item

gapDefault: "-". A string (one or more values) telling cpw what values indicate an alignment gap. Any non-base character is acceptable.

\item

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!

\item

\dotsCurrently 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: \itemcols\_align...Number of columns in each alignment \itemcols\_comparedNumber of columns compared (depends on ref) \itemn\_identNumber of columns that were identical \itemn\_diffNumber of columns that were different \itemn\_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]