findPalindromes          package:Biostrings          R Documentation

Searching a sequence for palindromes or complemented palindromes

Description:

     The 'findPalindromes' and 'findComplementedPalindromes' functions
     can be used to find palindromic or complemented palindromic
     regions in a sequence.

     'palindromeArmLength', 'palindromeLeftArm', 'palindromeRightArm',
     'complementedPalindromeArmLength', 'complementedPalindromeLeftArm'
     and 'complementedPalindromeRightArm' are utility functions for
     operating on palindromic or complemented palindromic sequences.

Usage:

       findPalindromes(subject, min.armlength=4, max.looplength=1, min.looplength=0, max.mismatch=0)
       palindromeArmLength(x, max.mismatch=0, ...)
       palindromeLeftArm(x, max.mismatch=0, ...)
       palindromeRightArm(x, max.mismatch=0, ...)

       findComplementedPalindromes(subject, min.armlength=4, max.looplength=1, min.looplength=0, max.mismatch=0)
       complementedPalindromeArmLength(x, max.mismatch=0, ...)
       complementedPalindromeLeftArm(x, max.mismatch=0, ...)
       complementedPalindromeRightArm(x, max.mismatch=0, ...)

Arguments:

 subject: An XString object containing the subject string, or an
          XStringViews object. 

min.armlength: An integer giving the minimum length of the arms of the
          palindromes (or complemented palindromes) to search for. 

max.looplength: An integer giving the maximum length of "the loop" (i.e
          the sequence separating the 2 arms) of the palindromes (or
          complemented palindromes) to search for. Note that by default
          ('max.looplength=1'), 'findPalindromes' will search for
          strict palindromes (or complemented palindromes) only. 

min.looplength: An integer giving the minimum length of "the loop" of
          the palindromes (or complemented palindromes) to search for. 

max.mismatch: The maximum number of mismatching letters allowed between
          the 2 arms of the palindromes (or complemented palindromes)
          to search for. 

       x: An XString object containing a 2-arm palindrome or
          complemented palindrome, or an XStringViews object containing
          a set of 2-arm palindromes or complemented palindromes. 

     ...: Additional arguments to be passed to or from methods. 

Details:

     The 'findPalindromes' function finds palindromic substrings in a
     subject string. The palindromes that can be searched for are
     either strict palindromes or 2-arm palindromes (the former being a
     particular case of the latter) i.e. palindromes where the 2 arms
     are separated by an arbitrary sequence called "the loop".

     Use the 'findComplementedPalindromes' function to find
     complemented palindromic substrings in a DNAString subject (in a
     complemented palindrome the 2 arms are reverse-complementary
     sequences).

Value:

     'findPalindromes' and 'findComplementedPalindromes' return an
     XStringViews object containing all palindromes (or complemented
     palindromes) found in 'subject' (one view per palindromic
     substring found).

     'palindromeArmLength' and 'complementedPalindromeArmLength' return
     the arm length (integer) of the 2-arm palindrome (or complemented
     palindrome) 'x'. It will raise an error if 'x' has no arms. Note
     that any sequence could be considered a 2-arm palindrome if we
     were OK with arms of length 0 but we are not: 'x' must have arms
     of length greater or equal to 1 in order to be considered a 2-arm
     palindrome. The same apply to 2-arm complemented palindromes. When
     applied to an XStringViews object 'x', 'palindromeArmLength' and
     'complementedPalindromeArmLength' behave in a vectorized fashion
     by returning an integer vector of the same length as 'x'.

     'palindromeLeftArm' and 'complementedPalindromeLeftArm' return an
     object of the same class as the original object 'x' and containing
     the left arm of 'x'.

     'palindromeRightArm' does the same as 'palindromeLeftArm' but on
     the right arm of 'x'.

     Like 'palindromeArmLength', both 'palindromeLeftArm' and
     'palindromeRightArm' will raise an error if 'x' has no arms. Also,
     when applied to an XStringViews object 'x', both behave in a
     vectorized fashion by returning an XStringViews object of the same
     length as 'x'.

Author(s):

     H. Pages

See Also:

     'maskMotif', 'matchPattern', 'matchLRPatterns', 'matchProbePair',
     XStringViews-class, DNAString-class

Examples:

       ## Note that complemented palindromes (like palindromes) can be nested
       findComplementedPalindromes(DNAString("ACGTTNAACGT-ACGTTNAACGT"))

       ## A real use case
       library(BSgenome.Dmelanogaster.UCSC.dm3)
       chrX <- Dmelanogaster$chrX
       chrX_pals <- findComplementedPalindromes(chrX, min.armlength=50, max.looplength=20)
       complementedPalindromeArmLength(chrX_pals)  # 251

       ## Of course, whitespaces matter
       palindromeArmLength(BString("was it a car or a cat I saw"))

       ## Note that the 2 arms of a strict palindrome (or strict complemented
       ## palindrome) are equal to the full sequence.
       palindromeLeftArm(BString("Delia saw I was aileD"))
       complementedPalindromeLeftArm(DNAString("N-ACGTT-AACGT-N"))
       palindromeLeftArm(DNAString("N-AAA-N-N-TTT-N"))

