replaceLetterAtLoc        package:Biostrings        R Documentation

_R_e_p_l_a_c_i_n_g _l_e_t_t_e_r_s _i_n _a _s_e_q_u_e_n_c_e _a_t _s_o_m_e _s_p_e_c_i_f_i_e_d _l_o_c_a_t_i_o_n_s

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

     'replaceLetterAtLoc' makes a copy of a sequence and replaces the
     original letters by new letters at some specified locations.

     Unlike 'replaceLetterAtLoc', '.inplaceReplaceLetterAtLoc' does IN
     PLACE replacement, therefore the user should NEVER USE IT as this
     would break all XString objects that are pointing to the modified
     external data. Its semantic is equivalent to calling
     'replaceLetterAtLoc' with 'if.not.extending="merge"' and
     'verbose=FALSE'. It is used by the 'injectSNPs' function in the
     BSgenome package, as part of the "lazy sequence loading"
     mechanism, for altering the original sequences of a BSgenome
     object at "sequence-load time". This alteration consists in
     injecting the IUPAC ambiguity letters representing the SNPs into
     the just loaded sequence, which is the only time where in place
     modification of the external data of an XString object is safe.

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

       replaceLetterAtLoc(x, loc, letter, if.not.extending="replace", verbose=FALSE)

       ## NEVER USE THIS FUNCTION!
       .inplaceReplaceLetterAtLoc(x, loc, letter)

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

       x: A DNAString object. 

     loc: An integer vector with no NAs specifying the locations where
          the replacements must occur. Note that locations can be
          repeated and in this case the last replacement to occur at a
          given location prevails. 

  letter: Character vector with no NAs. The total number of letters in
          'letter' ('sum(nchar(letter))') must be equal to the number
          of locations ('length(loc)'). 

if.not.extending: What to do if the new letter is not "extending" the
          old letter? The new letter "extends" the old letter if both
          are IUPAC letters and the new letter is as specific or less
          specific than the old one (e.g. M extends A, Y extends Y, but
          Y doesn't extend S). Possible values are '"replace"' (the
          default) for replacing in all cases, '"skip"' for not
          replacing when the new letter does not extend the old letter,
          '"merge"' for merging the new IUPAC letter with the old one,
          and '"error"' for raising an error.

          Note that the gap letter ("-") is not extending or extended
          by any other letter.

          Also note that '"merge"' is the only value for the
          'if.not.extending' argument that guarantees the final result
          to be independent on the order the replacement is performed
          (although this is only relevant when 'loc' contains
          duplicated locations, otherwise the result is always
          independent on the order, whatever the value of
          'if.not.extending' is). 

 verbose: When 'TRUE', a warning will report the number of skipped or
          merged letters. 

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

     A DNAString object of the same length as the orignal object 'x'
     for 'replaceLetterAtLoc'.

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

     H. Pages

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

     'chartr', 'injectHardMask', DNAString, 'IUPAC_CODE_MAP',
     'injectSNPs', BSgenome

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

       replaceLetterAtLoc(DNAString("AAMAA"), c(5, 1, 3, 1), "TYNC")
       replaceLetterAtLoc(DNAString("AAMAA"), c(5, 1, 3, 1), "TYNC", if.not.extending="merge")

