Add source classes for BED and generic Interval types

.gitignore

@@ -4,3 +4,5 @@ JeanLuc.iml
 target
 project/project
 .DS_Store
+out/
+*.iml

src/main/scala/com/fulcrumgenomics/fasta/SequenceDictionary.scala

@@ -26,13 +26,12 @@
 package com.fulcrumgenomics.fasta
 
 import java.io.StringWriter
-
 import com.fulcrumgenomics.FgBioDef
 import com.fulcrumgenomics.FgBioDef._
 import com.fulcrumgenomics.fasta.SequenceMetadata.Keys
 import com.fulcrumgenomics.util.Io
 import enumeratum.EnumEntry
-import htsjdk.samtools.util.BufferedLineReader
+import htsjdk.samtools.util.{BufferedLineReader, Locatable}
 import htsjdk.samtools.{SAMSequenceDictionary, SAMSequenceDictionaryCodec, SAMSequenceRecord, SAMTextHeaderCodec}
 import htsjdk.variant.utils.SAMSequenceDictionaryExtractor
 
@@ -247,6 +246,22 @@ case class SequenceDictionary(infos: IndexedSeq[SequenceMetadata]) extends Itera
     this.length == that.length && this.zip(that).forall { case (thisInfo, thatInfo) => thisInfo.sameAs(thatInfo) }
   }
 
+  /** Validate the locatable against the sequence dictionary.
+    *
+    * @throws NoSuchElementException when the locatable's contig cannot be found in the sequence dictionary.
+    * @throws IllegalArgumentException when the locatable's start is less than 1.
+    * @throws IllegalArgumentException when the locatable's end is beyond the reference contig length.
+    * @throws IllegalArgumentException when the locatable's start is greater than the end.
+    */
+  def validate(locatable: Locatable): Unit = {
+    val info = infos
+      .find(_.name == locatable.getContig)
+      .getOrElse(throw new NoSuchElementException(s"Contig does not exist within dictionary for locatable: $locatable."))
+    require(1 <= locatable.getStart, s"Start is less than 1 for locatable: $locatable.")
+    require(locatable.getEnd <= info.length, s"End is beyond the reference contig length for locatable: $locatable.")
+    require(locatable.getStart <= locatable.getEnd, f"Start is greater than end for locatable: $locatable.")
+  }
+
   /** Writes the sequence dictionary to the given path */
   def write(path: FilePath): Unit = {
     val writer = Io.toWriter(path)

src/main/scala/com/fulcrumgenomics/util/BedSource.scala

@@ -0,0 +1,116 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2021 Fulcrum Genomics
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+package com.fulcrumgenomics.util
+
+import com.fulcrumgenomics.commons.CommonsDef._
+import com.fulcrumgenomics.commons.collection.BetterBufferedIterator
+import com.fulcrumgenomics.fasta.SequenceDictionary
+import htsjdk.tribble.bed.BEDCodec.StartOffset
+import htsjdk.tribble.bed.{BEDCodec, BEDFeature}
+
+import java.io.{Closeable, File, InputStream}
+import scala.io.Source
+import scala.util.{Failure, Success, Try}
+
+/** A class for sourcing BED features from a stream of ASCII string data. */
+class BedSource private(
+  private val lines: Iterator[String],
+  private val sd: Option[SequenceDictionary] = None,
+  private val source: Option[{ def close(): Unit}] = None
+) extends Iterator[BEDFeature] with Closeable {
+
+  /** The underlying codec used to parse the lines of BED data. */
+  private val codec = new BEDCodec(StartOffset.ONE)
+
+  /** The current line count. */
+  private var lineNumber = 1L
+
+  /** The underlying buffered iterator of BED data. */
+  private val iter: BetterBufferedIterator[String] = lines match {
+    case iter: BetterBufferedIterator[String] => iter
+    case iter                                 => iter.bufferBetter
+  }
+
+  /** The header of this BED file. In most cases, the BED header is empty. */
+  val header: Seq[String] = {
+    val lines = iter.takeWhile(line => BedSource.HeaderPrefixes.exists(line.startsWith)).toIndexedSeq
+    lineNumber += lines.length
+    lines
+  }
+
+  /** The [[SequenceDictionary]] associated with the source. */
+  val dict: Option[SequenceDictionary] = sd
+
+  /** True if calling `next()` will yield another BED feature, false otherwise. */
+  override def hasNext: Boolean = iter.hasNext
+
+  /** Returns the next BED feature if available, or throws an exception if the feature is invalid or none is available. */
+  override def next(): BEDFeature = yieldAndThen(parse(iter.next()))(lineNumber += 1)
+
+  /** Parse a line of text and build a BED feature. */
+  private def parse(line: String): BEDFeature = {
+    val parsed  = codec.decode(line)
+    val feature = Option(parsed).getOrElse(throw new IllegalStateException(s"No BED feature could be built from line number: $lineNumber"))
+    Try(dict.foreach(_.validate(feature))) match {
+      case Success(())                          => feature
+      case Failure(e: NoSuchElementException)   => throw new NoSuchElementException(e.getMessage + s" Failed on line number: $lineNumber")
+      case Failure(e: IllegalArgumentException) => throw new IllegalArgumentException(e.getMessage + s" Failed on line number: $lineNumber")
+      case Failure(e: Throwable)                => throw new IllegalStateException(e.getMessage + s" Failed on line number: $lineNumber")
+    }
+  }
+
+  /** Closes the optional underlying handle. */
+  override def close(): Unit = this.source.foreach(_.close())
+}
+
+/** Companion object for [[BedSource]]. */
+object BedSource {
+
+  /** Common BED header line prefixes. */
+  val HeaderPrefixes: Seq[String] = Seq("#", "browser", "track")
+
+  /** Creates a new BED source from a sequence of lines. */
+  def apply(lines: Iterable[String], dict: Option[SequenceDictionary]): BedSource = new BedSource(lines.iterator, dict)
+
+  /** Creates a new BED source from an iterator of lines. */
+  def apply(lines: Iterator[String], dict: Option[SequenceDictionary]): BedSource = new BedSource(lines, dict)
+
+  /** Creates a new BED source from an input stream. */
+  def apply(stream: InputStream, dict: Option[SequenceDictionary]): BedSource = {
+    new BedSource(Source.fromInputStream(stream).getLines(), dict)
+  }
+
+  /** Creates a new BED source from a source. */
+  def apply(source: Source, dict: Option[SequenceDictionary]): BedSource = {
+    new BedSource(source.getLines(), dict, source = Some(source))
+  }
+
+  /** Creates a new BED source from a File. */
+  def apply(file: File, dict: Option[SequenceDictionary]): BedSource = apply(path = file.toPath, dict)
+
+  /** Creates a new BED source from a Path. */
+  def apply(path: PathToIntervals, dict: Option[SequenceDictionary]): BedSource = apply(Io.readLines(path), dict)
+}

src/main/scala/com/fulcrumgenomics/util/IntervalListSource.scala

@@ -27,18 +27,24 @@ package com.fulcrumgenomics.util
 
 
 import java.io.{Closeable, File, InputStream}
-
 import com.fulcrumgenomics.FgBioDef.{PathToIntervals, yieldAndThen}
 import com.fulcrumgenomics.commons.CommonsDef.BetterBufferedIteratorScalaWrapper
+import com.fulcrumgenomics.commons.collection.BetterBufferedIterator
 import com.fulcrumgenomics.commons.util.StringUtil
 import com.fulcrumgenomics.fasta.SequenceDictionary
+import com.fulcrumgenomics.util.IntervalListSource.HeaderPrefix
 import htsjdk.samtools.util.{BufferedLineReader, Interval, IntervalList}
 import htsjdk.samtools.{SAMFileHeader, SAMTextHeaderCodec}
 
 import scala.io.Source
+import scala.util.{Failure, Success, Try}
 
+/** Companion object for [[IntervalListSource]]. */
 object IntervalListSource {
 
+  /** The Interval List header line prefix. */
+  val HeaderPrefix: String = "@"
+
   /** Creates a new interval list source from a sequence of lines. */
   def apply(lines: Iterable[String]): IntervalListSource = new IntervalListSource(lines.iterator)
 
@@ -66,7 +72,10 @@ class IntervalListSource private(lines: Iterator[String],
                                  private[this] val source: Option[{ def close(): Unit }] = None)
   extends Iterator[Interval] with Closeable {
 
-  private val iter = lines.bufferBetter
+  private val iter: BetterBufferedIterator[String] = lines match {
+    case iter: BetterBufferedIterator[String] => iter
+    case iter                                 => iter.bufferBetter
+  }
 
   private var lineNumber = 1L
 
@@ -79,7 +88,7 @@ class IntervalListSource private(lines: Iterator[String],
   // Read the header
   val header: SAMFileHeader = {
     val codec = new SAMTextHeaderCodec
-    val headerLines = iter.takeWhile(_.startsWith("@")).toIndexedSeq
+    val headerLines = iter.takeWhile(_.startsWith(HeaderPrefix)).toIndexedSeq
     require(headerLines.nonEmpty, "No header found")
     lineNumber += headerLines.length
     val lineReader = BufferedLineReader.fromString(headerLines.mkString("\n"))
@@ -100,29 +109,24 @@ class IntervalListSource private(lines: Iterator[String],
   override def close(): Unit = this.source.foreach(_.close())
 
   private def parse(line: String): Interval = {
-    val fieldCount  = StringUtil.split(line, '\t', parseArray)
+    val fieldCount = StringUtil.split(line, '\t', parseArray)
     require(fieldCount == 5, s"Expected 5 fields on line $lineNumber")
-    val Array(refName: String, startString: String, endString: String, strand: String, name: String) = parseArray
-
-    val start = startString.toInt
-    val end   = endString.toInt
-
-    Option(dict(refName)) match {
-      case None =>
-        throw new IllegalArgumentException(f"Reference contig '$refName' not found in the sequence dictionary on line number $lineNumber.")
-      case Some(seq) =>
-        require(1 <= start, s"Start is less than 1 on line number $lineNumber")
-        require(end <= seq.length, s"End is beyond the reference contig length on line number $lineNumber")
-        require(start <= end, f"Start is greater than end on line number $lineNumber")
-    }
+    val Array(refName: String, start: String, end: String, strand: String, name: String) = parseArray
 
     val negative = strand match {
       case "-" => true
       case "+" => false
       case _   => throw new IllegalArgumentException(s"Unrecognized strand '$strand' on line number $lineNumber")
     }
 
-    new Interval(refName, start, end, negative, name)
+    val interval = new Interval(refName, start.toInt, end.toInt, negative, name)
+
+    Try(dict.validate(interval)) match {
+      case Success(())                          => interval
+      case Failure(e: NoSuchElementException)   => throw new NoSuchElementException(e.getMessage + s" Failed on line number: $lineNumber")
+      case Failure(e: IllegalArgumentException) => throw new IllegalArgumentException(e.getMessage + s" Failed on line number: $lineNumber")
+      case Failure(e: Throwable)                => throw new IllegalStateException(e.getMessage + s" Failed on line number: $lineNumber")
+    }
   }
 
   /** Reads in the intervals into an [[htsjdk.samtools.util.IntervalList]] */

src/main/scala/com/fulcrumgenomics/util/IntervalSource.scala

@@ -0,0 +1,113 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2021 Fulcrum Genomics
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+package com.fulcrumgenomics.util
+
+import com.fulcrumgenomics.commons.CommonsDef._
+import com.fulcrumgenomics.commons.collection.BetterBufferedIterator
+import com.fulcrumgenomics.fasta.SequenceDictionary
+import com.fulcrumgenomics.util.IntervalListSource.{HeaderPrefix => IntervalListHeaderPrefix}
+import htsjdk.samtools.SAMFileHeader
+import htsjdk.samtools.util.Interval
+import htsjdk.tribble.annotation.Strand
+
+import java.io.{Closeable, File, InputStream}
+import scala.io.Source
+
+/** A class for sourcing intervals from a stream of data that could either be in BED or Interval List format. */
+class IntervalSource private(
+  private val lines: Iterator[String],
+  private val sd: Option[SequenceDictionary],
+  private val source: Option[{ def close(): Unit }] = None
+) extends Iterator[Interval] with Closeable {
+
+  /** The underlying buffered iterator of interval data. */
+  private val iter: BetterBufferedIterator[String] = lines match {
+    case iter: BetterBufferedIterator[String] => iter
+    case iter                                 => iter.bufferBetter
+  }
+
+  private val (underlying: Iterator[Interval], _dict, _header) = if (
+    iter.headOption.exists(_.startsWith(IntervalListHeaderPrefix))
+  ) {
+    val wrapped = IntervalListSource(iter)
+    require(sd.forall(wrapped.dict.sameAs), "Provided sequence dictionary does not match the input's dict header!")
+    (wrapped, Some(wrapped.dict), Some(wrapped.header))
+  } else {
+    val wrapped = BedSource(iter, sd).map { bed =>
+      new Interval(
+        bed.getContig,
+        bed.getStart,
+        bed.getEnd,
+        // BEDFeature.getStrand() can be null so wrap in an option and search for the negative enum.
+        Option(bed.getStrand).contains(Strand.NEGATIVE),
+        // The default name for BEDFeature is the empty string (""), but defaults to null for Interval.
+        if (bed.getName == "") null else bed.getName
+      )
+    }
+    (wrapped, sd, None)
+  }
+
+  /** The [[SAMFileHeader]] associated with the source, if it exists. */
+  val header: Option[SAMFileHeader] = _header
+
+  /** The [[SequenceDictionary]] associated with the source, if it exists. */
+  val dict: Option[SequenceDictionary] = _dict
+
+  /** True if calling `next()` will yield another interval, false otherwise. */
+  override def hasNext: Boolean = underlying.hasNext
+
+  /** Returns the next interval if available, or throws an exception if none is available. */
+  override def next(): Interval = underlying.next()
+
+  /** Closes the underlying reader. */
+  override def close(): Unit = this.source.foreach(_.close())
+}
+
+/** Companion object for [[IntervalSource]]. */
+object IntervalSource {
+
+  /** Creates a new interval source from a sequence of lines. */
+  def apply(lines: Iterable[String], dict: Option[SequenceDictionary]): IntervalSource = new IntervalSource(lines.iterator, dict)
+
+  /** Creates a new interval source from an iterator of lines. */
+  def apply(lines: Iterator[String], dict: Option[SequenceDictionary]): IntervalSource = new IntervalSource(lines, dict)
+
+  /** Creates a new interval source from an input stream. */
+  def apply(stream: InputStream, dict: Option[SequenceDictionary]): IntervalSource = {
+    new IntervalSource(Source.fromInputStream(stream).getLines(), dict)
+  }
+
+  /** Creates a new interval source from a source. */
+  def apply(source: Source, dict: Option[SequenceDictionary]): IntervalSource = {
+    new IntervalSource(source.getLines(), dict, source = Some(source))
+  }
+
+  /** Creates a new interval source from a File. */
+  def apply(file: File, dict: Option[SequenceDictionary]): IntervalSource = apply(path = file.toPath, dict)
+
+  /** Creates a new interval source from a Path. */
+  def apply(path: PathToIntervals, dict: Option[SequenceDictionary]): IntervalSource = apply(Io.readLines(path), dict)
+}

src/main/scala/com/fulcrumgenomics/util/Io.scala

@@ -21,16 +21,16 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.fulcrumgenomics.util
 
-import java.io.{InputStream, OutputStream}
-import java.nio.file.{Files, Path, Paths}
-import java.util.zip.{GZIPInputStream, GZIPOutputStream}
+package com.fulcrumgenomics.util
 
-import com.fulcrumgenomics.commons.CommonsDef.DirPath
+import com.fulcrumgenomics.commons.CommonsDef._
 import com.fulcrumgenomics.commons.io.{IoUtil, PathUtil}
 import htsjdk.samtools.util.BlockCompressedOutputStream
 
+import java.io.OutputStream
+import java.nio.file.{Files, Path, Paths}
+
 /**
   * Provides common IO utility methods.  Can be instantiated to create a custom factory, or
   * the companion object can be used as a singleton version.
@@ -51,7 +51,7 @@ class Io(var compressionLevel: Int = 5,
   override def makeTempDir(name: String): DirPath = Files.createTempDirectory(tmpDir, name)
 
   /** Overridden to ensure that tmp files are created within the correct tmpDir. */
-  override def makeTempFile(prefix: String, suffix: String, dir: Option[DirPath] = Some(tmpDir)): DirPath = super.makeTempFile(prefix, suffix, dir)
+  override def makeTempFile(prefix: String, suffix: String, dir: Option[DirPath] = Some(tmpDir)): FilePath = super.makeTempFile(prefix, suffix, dir)
 }
 
 /** Singleton object that can be used when the default buffer size and compression are desired. */