MaskedXString-class        package:Biostrings        R Documentation

MaskedXString objects

Description:

     The MaskedBString, MaskedDNAString, MaskedRNAString and
     MaskedAAString classes are containers for storing masked
     sequences.

     All those containers derive directly (and with no additional
     slots) from the MaskedXString virtual class.

Details:

     In Biostrings, a pile of masks can be put on top of a sequence. A
     pile of masks is represented by a MaskCollection  object and the
     sequence by an XString object. A MaskedXString object is the
     result of bundling them together in a single object.

     Note that, no matter what masks are put on top of it, the original
     sequence is always stored unmodified in a MaskedXString object.
     This allows the user to activate/deactivate masks without having
     to worry about losing the information stored in the
     masked/unmasked regions. Also this allows efficient memory
     management since the original sequence never needs to be copied
     (modifying it would require to make a copy of it first - sequences
     cannot and should never be modified in place in Biostrings), even
     when the set of active/inactive masks changes.

Accessor methods:

     In the code snippets below, 'x' is a MaskedXString object. For
     'masks(x)' and 'masks(x) <- y', it can also be an XString object
     and 'y' must be 'NULL' or a MaskCollection object.


      'unmasked(x)': Turns 'x' into an XString object by dropping the
          masks.

      'masks(x)': Turns 'x' into a MaskCollection object by  dropping
          the sequence.

      'masks(x) <- y': If 'x' is an XString object and 'y' is 'NULL',
          then this doesn't do anything.

          If 'x' is an XString object and 'y' is a MaskCollection
          object, then this turns 'x' into a MaskedXString object by
          putting the masks in 'y' on top of it.

          If 'x' is a MaskedXString object and 'y' is 'NULL', then this
          is equivalent to 'x <- unmasked(x)'.

          If 'x' is a MaskedXString object and 'y' is a MaskCollection
          object, then this replaces the masks currently on top of 'x'
          by the masks in 'y'. 

      'alphabet(x)': Equivalent to 'alphabet(unmasked(x))'. See
          '?alphabet' for more information.

      'length(x)': Equivalent to 'length(unmasked(x))'. See
          '?`length,XString-method`' for more information.


"maskedwidth" and related methods:

     In the code snippets below, 'x' is a MaskedXString object.


      'maskedwidth(x)': Get the number of masked letters in 'x'. A
          letter is considered masked iff it's masked by at least one
          active mask.

      'maskedratio(x)': Equivalent to 'maskedwidth(x) / length(x)'.

      'nchar(x)': Equivalent to 'length(x) - maskedwidth(x)'.


Coercion:

     In the code snippets below, 'x' is a MaskedXString object.


      'as(x, "XStringViews")': Turns 'x' into an XStringViews object
          where the views are the unmasked regions of the original
          sequence ("unmasked" means not masked by at least one active
          mask).


Other methods:

     In the code snippets below, 'x' is a MaskedXString object.


      'collapse(x)': Collapses the set of masks in 'x' into a single
          mask made of all active masks.

      'gaps(x)': Reverses all the masks i.e. each mask is replaced by a
          mask where previously unmasked regions are now masked and
          previously masked regions are now unmasked.


Author(s):

     H. Pages

See Also:

     'maskMotif', 'injectHardMask', 'alphabetFrequency',
     'reverse,MaskedXString-method', XString-class,
     MaskCollection-class, XStringViews-class, Ranges-utils

Examples:

       ## ---------------------------------------------------------------------
       ## A. MASKING BY POSITION
       ## ---------------------------------------------------------------------
       mask0 <- Mask(mask.width=29, start=c(3, 10, 25), width=c(6, 8, 5))
       x <- DNAString("ACACAACTAGATAGNACTNNGAGAGACGC")
       length(x)  # same as width(mask0)
       nchar(x)   # same as length(x)
       masks(x) <- mask0
       x
       length(x)  # has not changed
       nchar(x)   # has changed
       gaps(x)

       ## Prepare a MaskCollection object of 3 masks ('mymasks') by running the
       ## examples in the man page for these objects:
       example(MaskCollection, package="IRanges")

       ## Put it on 'x':
       masks(x) <- mymasks
       x
       alphabetFrequency(x)

       ## Deactivate all masks:
       active(masks(x)) <- FALSE
       x

       ## Activate mask "C":
       active(masks(x))["C"] <- TRUE
       x

       ## Turn MaskedXString object into an XStringViews object:
       as(x, "XStringViews")

       ## Drop the masks:
       masks(x) <- NULL
       x
       alphabetFrequency(x)

       ## ---------------------------------------------------------------------
       ## B. MASKING BY CONTENT
       ## ---------------------------------------------------------------------
       ## See ?maskMotif for masking by content

