MaskedXString-class        package:Biostrings        R Documentation

_M_a_s_k_e_d_X_S_t_r_i_n_g _o_b_j_e_c_t_s

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

     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. They are also said to
     be MaskedXString subtypes.

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

     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.

_A_c_c_e_s_o_r _m_e_t_h_o_d_s:

     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.


"_m_a_s_k_e_d_w_i_d_t_h" _a_n_d _r_e_l_a_t_e_d _m_e_t_h_o_d_s:

     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)'.


_C_o_e_r_c_i_o_n:

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


_O_t_h_e_r _m_e_t_h_o_d_s:

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


      'reduce(x)': Reduce the set of masks in 'x' to 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.


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

     H. Pages

_S_e_e _A_l_s_o:

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

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

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

