@@ -68,7 +68,7 @@ Collate:

     collapseBSseq.R

     FWIRanges-class.R

     FWGRanges-class.R

-    findCytosines.R

+    findLoci.R

 License: Artistic-2.0

 VignetteBuilder: knitr

 URL: https://github.com/kasperdanielhansen/bsseq

@@ -71,8 +71,7 @@ exportMethods("[", "show",

               "sampleNames", "sampleNames<-",

               "pData", "pData<-",

               "findOverlaps", "subsetByOverlaps",

-              "combine", "updateObject",

-              "findCytosines")

+              "combine", "updateObject")

 export("BSseq", "getMeth", "getCoverage", "getBSseq", "getStats",

        "collapseBSseq", "orderBSseq", "hasBeenSmoothed", "chrSelectBSseq",

@@ -83,7 +82,7 @@ export("BSseq", "getMeth", "getCoverage", "getBSseq", "getStats",

        "poissonGoodnessOfFit", "binomialGoodnessOfFit",

        "data.frame2GRanges", "BSseqTstat",

        "BSseqStat",

-       "findCytosines")

+       "findLoci")

 S3method("print", "chisqGoodnessOfFit")

 S3method("plot", "chisqGoodnessOfFit")

deleted file mode 100644

@@ -1,73 +0,0 @@

-# Exported generics ------------------------------------------------------------

-

-setGeneric(

-    "findCytosines",

-    function(x, context, seqlevels,

-             strand = c("*", "+", "-")) standardGeneric("findCytosines"),

-    signature = "x")

-

-# Exported methods -------------------------------------------------------------

-

-setMethod(

-    "findCytosines",

-    "BSgenome",

-    function(x, context, seqlevels = seqlevels(x), strand = c("*", "+", "-")) {

-        strand <- match.arg(strand)

-        # NOTE: vmatchPattern,BSgenome-method returns a GRanges instance and

-        #       automatically checks both forward and reverse strands.

-        gr <- vmatchPattern(

-            pattern = context,

-            subject = x,

-            exclude = setdiff(seqlevels(x), seqlevels),

-            fixed = "subject")

-        if (strand == "+") {

-            gr <- gr[strand(gr) == "+"]

-        } else if (strand == "-") {

-            gr <- gr[strand(gr) == "-"]

-        }

-        # NOTE: Want just the position of the cytosine.

-        resize(gr, width = 1L, fix = "start")

-    }

-)

-

-# TODO: Replace with vmatchPDict() when/if this is available, where the pdict

-#       argument is a DNAStringSet including the original context and its

-#       reverse complement.

-setMethod(

-    "findCytosines",

-    "DNAStringSet",

-    function(x, context, seqlevels = seqlevels(x), strand = c("*", "+", "-")) {

-        context <- DNAString(context)

-        x <- x[seqlevels]

-        strand <- match.arg(strand)

-        if (strand %in% c("*", "+")) {

-            fwd_gr <- as(

-                vmatchPattern(

-                    pattern = context,

-                    subject = x,

-                    fixed = "subject"),

-                "GRanges")

-            strand(fwd_gr) <- "+"

-        } else {

-            fwd_gr <- GRanges()

-        }

-        if (strand %in% c("*", "-")) {

-            rev_gr <- as(

-                vmatchPattern(

-                    pattern = reverseComplement(context),

-                    subject = x,

-                    fixed = "subject"),

-                "GRanges")

-            strand(rev_gr) <- "-"

-        } else {

-            rev_gr <- GRanges()

-        }

-        gr <- c(fwd_gr, rev_gr)

-        # NOTE: Want just the position of the cytosine.

-        resize(gr, width = 1L, fix = "start")

-    }

-)

-

-# TODOs ------------------------------------------------------------------------

-

-# TODO: Default value of seqlevels isn't working.

new file mode 100644

@@ -0,0 +1,73 @@

+# Exported functions -----------------------------------------------------------

+

+findLoci <- function(pattern, subject, include = seqlevels(subject),

+                     strand = c("*", "+", "-"), fixed = "subject",

+                     resize = TRUE) {

+    pattern <- DNAString(pattern)

+    strand <- match.arg(strand)

+

+    if (is.character(subject) || is(subject, "RTLFile")) {

+        if (!requireNamespace("rtracklayer", quietly = TRUE)) {

+            stop("rtracklayer package required for importing 'subject'.")

+        }

+        subject <- try(rtracklayer::import(subject), silent = TRUE)

+        if (!is(subject, "DNAStringSet")) {

+            stop("Unable to import 'subject' as a DNAStringSet.")

+        }

+    }

+

+    if (is(subject, "BSgenome")) {

+        # NOTE: vmatchPattern,BSgenome-method returns a GRanges instance and

+        #       automatically checks both forward and reverse strands.

+        gr <- vmatchPattern(

+            pattern = pattern,

+            subject = subject,

+            # NOTE: This must be a regular expression;

+            #       see https://github.com/Bioconductor/BSgenome/issues/1.

+            exclude = paste0("^", setdiff(seqnames(subject), include), "$"),

+            fixed = fixed)

+        if (identical(strand, "+")) {

+            gr <- gr[strand(gr) == "+"]

+        } else if (identical(strand, "-")) {

+            gr <- gr[strand(gr) == "-"]

+        }

+    } else if (is(subject, "DNAStringSet")) {

+        subject <- subject[include]

+        if (strand %in% c("*", "+")) {

+            fwd_gr <- as(

+                vmatchPattern(

+                    pattern = pattern,

+                    subject = subject,

+                    fixed = fixed),

+                "GRanges")

+            strand(fwd_gr) <- "+"

+        } else {

+            fwd_gr <- GRanges()

+        }

+        if (strand %in% c("*", "-")) {

+            rev_gr <- as(

+                vmatchPattern(

+                    pattern = reverseComplement(pattern),

+                    subject = subject,

+                    fixed = fixed),

+                "GRanges")

+            strand(rev_gr) <- "-"

+        } else {

+            rev_gr <- GRanges()

+        }

+        gr <- c(fwd_gr, rev_gr)

+    } else {

+        stop("Cannot handle 'subject' of class ", class(subject), ".")

+    }

+

+    if (resize) {

+        gr <- resize(gr, width = 1L, fix = "start")

+    }

+    gr

+}

+

+# TODOs ------------------------------------------------------------------------

+

+# TODO: Default value of seqlevels may not be working.

+# TODO: What happens if subject is a non-filepath character (e.g., "CATGCG") or

+#       a DNAString?

new file mode 100644

@@ -0,0 +1,76 @@

+\name{findLoci}

+\alias{findLoci}

+\title{

+  Find methylation loci in a genome

+}

+\description{

+    This is a convenience function to find methylation loci, such as CpGs, in a reference genome.

+    The result is useful as the value of the \code{loci} argument for \code{\link{read.bismark}()}.

+}

+\usage{

+findLoci(pattern,

+         subject,

+         include = seqlevels(subject),

+         strand = c("*", "+", "-"),

+         fixed = "subject",

+         resize = TRUE)

+}

+\arguments{

+  \item{pattern}{

+    A string specifying the pattern to search for, e.g. \code{"CG"}.

+    Can contain IUPAC ambiguity codes, e.g., \code{"CH"}.

+  }

+  \item{subject}{

+    A string containing a file path to the genome sequence, in FASTA or 2bit format, to be searched.

+    Alternatively, a \linkS4class{BSgenome} or \linkS4class{DNAStringSet} object storing the genome sequence to be searched.

+  }

+  \item{include}{

+    A character vector indicating the seqlevels of \code{subject} to be used.

+  }

+  \item{strand}{

+    A character scaler specifying the strand of \code{subject} to be used.

+    If \code{strand = "*"}, then both the positive (\code{strand = "+"}) and negative (\code{strand = "-"} strands will be searched.)

+    It is assumed that \code{subject} contains the sequence with respect to the \code{+} strand.

+  }

+  \item{fixed}{

+    If \code{"subject"} (the default), IUPAC ambiguity codes in the pattern only are interpreted as wildcards, e.g., a \code{pattern} containing \code{CH} matches a \code{subject} containing \code{CA} but not vice versa.

+    See \code{?Biostrings::`\link[Biostrings]{lowlevel-matching}`} for more information

+  }

+  \item{resize}{

+    A logical scalar specifying whether the ranges should be shifted to have width 1 and anchored by the start of the locus, e.g., resize a CpG dinucleotide to give the co-ordinates of the cytosine.

+  }

+}

+\details{

+  This function provides a convenience wrapper for finding methylation loci in a genome, based on running \code{\link[Biostrings]{vmatchPattern}()}.

+  Users requiring finer-grained control should directly use the \code{\link[Biostrings]{vmatchPattern}()} function and coerce the result to a \linkS4class{GRanges} object.

+}

+\value{

+  A \linkS4class{GRanges} object storing the found loci.

+}

+\author{

+  Peter F. Hickey

+}

+\seealso{

+  \itemize{

+    \item \code{Biostrings::\link[Biostrings]{vmatchPattern}()}

+    \item \code{?BSgenome::`\link[BSgenome]{BSgenome-utils}`}

+    }

+}

+\examples{

+  library(Biostrings)

+  # Find CpG dinucleotides on the both strands of an artificial sequence

+  my_seq <- DNAStringSet("ATCAGTCGC")

+  names(my_seq) <- "test"

+  findLoci(pattern = "CG", subject = my_seq)

+  # Find CHG trinucleotides on the both strands of an artificial sequence

+  findLoci(pattern = "CHG", subject = my_seq)

+

+  # Find CpG dinucleotides on the + strand of chr17 from the human genome (hg38)

+  if (requireNamespace("BSgenome.Hsapiens.UCSC.hg38")) {

+    findLoci(

+        pattern = "CG",

+        subject = BSgenome.Hsapiens.UCSC.hg38::BSgenome.Hsapiens.UCSC.hg38,

+        include = "chr17",

+        strand = "+")

+  }

+}