cpw               package:ComPairWise               R Documentation

_C_o_m_p_a_r_e _a_l_t_e_r_n_a_t_e _a_l_i_g_n_m_e_n_t_s _o_f _p_h_y_l_o_g_e_n_e_t_i_c _o_r _p_o_p_u_l_a_t_i_o_n _g_e_n_e_t_i_c _d_a_t_a

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

   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

_D_e_t_a_i_l_s:

     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:

'_n_a_m_e_1, _n_a_m_e_2' 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.

'_r_e_f' 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?

'_o_u_t' 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".

'_o_u_t_f_i_l_e' 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.

'_g_r_a_p_h' 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. 

'_g_r._f_i_l_e' 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.

'_p_a_i_r_w_i_s_e' 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.

'_o_n_e_g_r_a_p_h' Default: TRUE.  If multiple comparisons are being done,
     should graphical output all be on one graph, or separate graphs?

'_n_e_x_u_s._o_u_t' Default: TRUE.  Should the text output include a
     NEXUS-format sets block with a character set for identical and
     non-identical columns?

'_k_e_e_p' 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.

'_g_a_p' Default: "-".  A string (one or more values) telling cpw what
     values indicate an alignment gap.  Any non-base character is
     acceptable.

'_m_i_s_s' 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).

_V_a_l_u_e:

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

  totals: Summary list:

     _c_o_l_s__a_l_i_g_n... Number of columns in each alignment

     _c_o_l_s__c_o_m_p_a_r_e_d Number of columns compared (depends on ref)

     _n__i_d_e_n_t Number of columns that were identical

     _n__d_i_f_f Number of columns that were different

     _n__g_a_p__m_i_s_s 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

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

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

_E_x_a_m_p_l_e_s:

     #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)

