PairwiseAlignedXStringSet-class  package:Biostrings  R Documentation

PairwiseAlignedXStringSet, PairwiseAlignedFixedSubject, and
PairwiseAlignedFixedSubjectSummary objects

Description:

     The 'PairwiseAlignedXStringSet' class is a container for storing
     an elementwise pairwise alignment. The
     'PairwiseAlignedFixedSubject' class is a container for storing a
     pairwise alignment with a single subject. The
     'PairwiseAlignedFixedSubjectSummary' class is a container for
     storing the summary of an alignment.

Usage:

       ## Constructors:
       ## When subject is missing, pattern must be of length 2
       ## S4 method for signature 'XString, XString':
       PairwiseAlignedXStringSet(pattern, subject,
         type = "global", substitutionMatrix = NULL, gapOpening = 0, gapExtension = -1)
       ## S4 method for signature 'XStringSet, missing':
       PairwiseAlignedXStringSet(pattern, subject,
         type = "global", substitutionMatrix = NULL, gapOpening = 0, gapExtension = -1)
       ## S4 method for signature 'character, character':
       PairwiseAlignedXStringSet(pattern, subject,
         type = "global", substitutionMatrix = NULL, gapOpening = 0, gapExtension = -1,
         baseClass = "BString")
       ## S4 method for signature 'character, missing':
       PairwiseAlignedXStringSet(pattern, subject,
         type = "global", substitutionMatrix = NULL, gapOpening = 0, gapExtension = -1,
         baseClass = "BString")

Arguments:

 pattern: a character vector of length 1 or 2, an 'XString', or an
          'XStringSet' object of length 1 or 2.

 subject: a character vector of length 1 or an 'XString' object.

    type: type of alignment. One of '"global"', '"local"', '"overlap"',
          '"global-local"', and '"local-global"' where '"global"' =
          align whole strings with end gap penalties, '"local"' = align
          string fragments, '"overlap"' = align whole strings without
          end gap penalties, '"global-local"' = align whole strings
          with end gap penalties on 'pattern' and without end gap
          penalties on 'subject'. '"local-global"' = align whole
          strings without end gap penalties on 'pattern' and with end
          gap penalties on 'subject'.

substitutionMatrix: substitution matrix for the alignment. If NULL, the
          diagonal values and off-diagonal values are set to 0 and 1
          respectively.

gapOpening: the cost for opening a gap in the alignment.

gapExtension: the incremental cost incurred along the length of the gap
          in the alignment.

baseClass: the base 'XString' class to use in the alignment.

Details:

     Before we define the notion of alignment, we introduce the notion
     of "filled-with-gaps subsequence". A "filled-with-gaps
     subsequence" of a string string1 is obtained by inserting 0 or any
     number of gaps in a subsequence of s1. For example L-A-ND and
     A-N-D are "filled-with-gaps subsequences" of LAND. An alignment
     between two strings string1 and string2 results in two strings
     (align1 and align2) that have the same length and are
     "filled-with-gaps subsequences" of string1 and string2.

     For example, this is an alignment between LAND and LEAVES:


         L-A
         LEA

     An alignment can be seen as a compact representation of one set of
     basic operations that transforms string1 into align1. There are 3
     different kinds of basic operations: "insertions" (gaps in
     align1), "deletions" (gaps in align2),  "replacements". The above
     alignment represents the following basic operations:


         insert E at pos 2
         insert V at pos 4
         insert E at pos 5
         replace by S at pos 6 (N is replaced by S)
         delete at pos 7 (D is deleted)

     Note that "insert X at pos i" means that all letters at a position
     >= i are moved 1 place to the right before X is actually inserted.

     There are many possible alignments between two given strings
     string1 and string2 and a common problem is to find the one (or
     those ones) with the highest score, i.e. with the lower total cost
     in terms of basic operations.

Object extraction methods:

     In the code snippets below, 'x' is a 'PairwiseAlignedXStringSet'
     object, except otherwise noted.


      'pattern(x)': The 'AlignedXStringSet' object for the pattern.

      'subject(x)': The 'AlignedXStringSet' object for the subject.

      'summary(object, ...)': Generates a summary for the
          'PairwiseAlignedXStringSet'.


General information methods:

     In the code snippets below, 'x' is a 'PairwiseAlignedXStringSet'
     object, except otherwise noted.


      'alphabet(x)': Equivalent to 'alphabet(unaligned(subject(x)))'.

      'length(x)': The length of the 'aligned(pattern(x))' and
          'aligned(subject(x))'.  There is a method for
          'PairwiseAlignedFixedSubjectSummary' as well.

      'type(x)': The type of the alignment ('"global"', '"local"',
          '"overlap"', '"global-local"', or '"local-global"'). There is
          a method for 'PairwiseAlignedFixedSubjectSummary' as well.


Aligned sequence methods:

     In the code snippets below, 'x' is a 'PairwiseAlignedFixedSubject'
     object, except otherwise noted. 


      'aligned(x, degap = FALSE, gapCode="-", endgapCode="-")': If
          'degap = FALSE', "align" the alignments by returning an
          'XStringSet' object containing the aligned patterns without
          insertions. If 'degap = TRUE', returns 'aligned(pattern(x),
          degap=TRUE)'. The 'gapCode' and 'endgapCode' arguments denote
          the code in the appropriate 'alphabet' to use for the
          internal and end gaps.

      'as.character(x)': Converts 'aligned(x)' to a character vector.

      'as.matrix(x)': Returns an "exploded" character matrix
          representation of 'aligned(x)'.

      'toString(x)': Equivalent to 'toString(as.character(x))'.


Subject position methods:

     In the code snippets below, 'x' is a 'PairwiseAlignedFixedSubject'
     object, except otherwise noted.


      'consensusMatrix(x, as.prob=FALSE, baseOnly=FALSE, gapCode="-",
          endgapCode="-")' See `consensusMatrix` for more information.

      'consensusString(x)' See `consensusString` for more information.

      'coverage(x, shift=0L, width=NULL, weight=1L)' See
          `coverage,PairwiseAlignedFixedSubject-method` for more
          information.

      'Views(subject, start=NULL, end=NULL, width=NULL, names=NULL)':
          The 'XStringViews' object that represents the pairwise
          alignments along 'unaligned(subject(subject))'. The 'start'
          and 'end' arguments must be either 'NULL'/'NA' or an integer
          vector of length 1 that denotes the offset from
          'start(subject(subject))'.


Numeric summary methods:

     In the code snippets below, 'x' is a 'PairwiseAlignedXStringSet'
     object, except otherwise noted.


      'nchar(x)': The nchar of the 'aligned(pattern(x))' and
          'aligned(subject(x))'. There is a method for
          'PairwiseAlignedFixedSubjectSummary' as well.

      'insertion(x)': An 'CompressedIRangesList' object containing the 
          locations of the insertions from the perspective of the
          'pattern'.

      'deletion(x)': An 'CompressedIRangesList' object containing the 
          locations of the deletions from the perspective of the
          'pattern'.

      'indel(x)': An 'InDel' object containing the locations of the
          insertions and deletions from the perspective of the
          'pattern'.

      'nindel(x)': An 'InDel' object containing the number of
          insertions and deletions.

      'score(x)': The score of the alignment. There is a method for
          'PairwiseAlignedFixedSubjectSummary' as well.


Subsetting methods:


      'x[i]': Returns a new 'PairwiseAlignedXStringSet' object made of
          the selected elements.

      'rep(x, times)': Returns a new 'PairwiseAlignedXStringSet' object
          made of the repeated elements.


Author(s):

     P. Aboyoun

See Also:

     'pairwiseAlignment', 'AlignedXStringSet-class', 'XString-class',
     'XStringViews-class', 'align-utils', 'pid'

Examples:

       PairwiseAlignedXStringSet("-PA--W-HEAE", "HEAGAWGHE-E")
       pattern <- AAStringSet(c("HLDNLKGTF", "HVDDMPNAL"))
       subject <- AAString("SMDDTEKMSMKL")
       nw1 <- pairwiseAlignment(pattern, subject, substitutionMatrix = "BLOSUM50",
         gapOpening = -3, gapExtension = -1)
       pattern(nw1)
       subject(nw1)
       aligned(nw1)
       as.character(nw1)
       as.matrix(nw1)
       nchar(nw1)
       score(nw1)
       nw1

