replaceLetterAtLoc {Biostrings}R Documentation

Replacing letters in a sequence at some specified locations

Description

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.

Usage

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

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

Arguments

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.

Value

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

Author(s)

H. Pages

See Also

chartr, injectHardMask, DNAString, IUPAC_CODE_MAP, injectSNPs, BSgenome

Examples

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

[Package Biostrings version 2.8.18 Index]