Add an option to sort by sequence role in CollectAlternateContigNames (#868)

* [feat] Add an option to sort by sequence role in CollectAlternateContigNames

Author: nh13

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

@@ -96,8 +96,9 @@ object SequenceRole extends FgBioEnum[SequenceRole] {
     SequenceRole(roleValue)
   }
 
-  case object AltScaffold         extends SequenceRole { val key: String = "alt-scaffold" }
+  // NB: the order in which these are defined is important for when `--sort-by-sequence-role` is used
   case object AssembledMolecule   extends SequenceRole { val key: String = "assembled-molecule" }
+  case object AltScaffold         extends SequenceRole { val key: String = "alt-scaffold" }
   case object FixPatch            extends SequenceRole { val key: String = "fix-patch" }
   case object NovelPatch          extends SequenceRole { val key: String = "novel-patch" }
   case object UnlocalizedScaffold extends SequenceRole { val key: String = "unlocalized-scaffold" }
@@ -131,9 +132,11 @@ class CollectAlternateContigNames
  @arg(flag='a', doc="The assembly report column(s) for the alternate contig name(s)", minElements=1) val alternates: Seq[AssemblyReportColumn],
  @arg(flag='s', doc="Only output sequences with the given sequence roles.  If none given, all sequences will be output.", minElements=0)
   val sequenceRoles: Seq[SequenceRole] = Seq.empty,
- @arg(flag='d', doc="Update an existing sequence dictionary file.  The primary names must match.") val existing: Option[PathToSequenceDictionary] = None,
+ @arg(flag='d', doc="Update an existing sequence dictionary file.  The primary names must match.", mutex=Array("sortBySequencingRole")) val existing: Option[PathToSequenceDictionary] = None,
  @arg(flag='x', doc="Allow mismatching sequence lengths when using an existing sequence dictionary file.") val allowMismatchingLengths: Boolean = false,
- @arg(doc="Skip contigs that have no alternates") val skipMissingAlternates: Boolean = true
+ @arg(doc="Skip contigs that have no alternates") val skipMissingAlternates: Boolean = true,
+ @arg(doc="Sort by the sequencing role (only when not updating an existing sequence dictionary file).  Uses the order from `--sequence-roles` if provided.", mutex=Array("existing"))
+ val sortBySequencingRole: Boolean = false,
 ) extends FgBioTool with LazyLogging {
 
   import com.fulcrumgenomics.fasta.{AssemblyReportColumn => Column}
@@ -213,7 +216,17 @@ class CollectAlternateContigNames
 
     // Apply to an existing sequence dictionary if necessary
     val dict: SequenceDictionary = existing match {
-      case None => SequenceDictionary(metadatas.toSeq:_*)
+      case None if !sortBySequencingRole => SequenceDictionary(metadatas.toSeq:_*)
+      case None =>
+        // Use the user-provided roles, otherwise use all role
+        val roles = (if (sequenceRoles.nonEmpty) sequenceRoles.toIndexedSeq else SequenceRole.values)
+          .zipWithIndex
+          .map { case (role, index) =>  role.key -> index }
+          .toMap
+        val metas = metadatas.toSeq.sortBy { metadata =>
+          metadata.get(Column.SequenceRole.tag).flatMap { name => roles.get(name) }.getOrElse(roles.size)
+        }.zipWithIndex.map { case (metadata, index) => metadata.copy(index=index) }
+        SequenceDictionary(metas:_*)
       case Some(path) =>
         val assemblyReportMetadataMap = metadatas.map { m => (m.name, m) }.toMap
         val updatedMetadatas          = SequenceDictionary(path).map { existingMetadata =>

src/test/scala/com/fulcrumgenomics/fasta/CollectAlternateContigNamesTest.scala

@@ -147,4 +147,45 @@ class CollectAlternateContigNamesTest extends UnitSpec {
     dict.last.name shouldBe "NC_012920.1"
     dict.last.aliases should contain theSameElementsInOrderAs Seq("J01415.2", "chrM")
   }
+
+  it should "sort by sequencing roles when they all are defined" in {
+    val output = makeTempFile("test.", ".dict")
+    val tool = new CollectAlternateContigNames(
+      input                = reportHg19,
+      output               = output,
+      primary              = Column.RefSeqAccession,
+      alternates           = Seq(Column.UcscName),
+      sequenceRoles        = Seq(UnplacedScaffold, UnlocalizedScaffold, AssembledMolecule),
+      sortBySequencingRole = true
+    )
+    executeFgbioTool(tool)
+
+    val dict = SequenceDictionary(output)
+    dict should have length 84
+    dict.head.name shouldBe "NT_113961.1"
+    dict.head.aliases should contain theSameElementsInOrderAs Seq("chrUn_gl000211")
+    dict.last.name shouldBe "NC_012920.1"
+    dict.last.aliases should contain theSameElementsInOrderAs Seq("chrM")
+    dict.map(m => m(Column.SequenceRole.tag)).toIndexedSeq.distinct should contain theSameElementsInOrderAs Seq(UnplacedScaffold, UnlocalizedScaffold, AssembledMolecule).map(_.key)
+  }
+
+  it should "sort by sequencing roles when no roles are defined" in {
+    val output = makeTempFile("test.", ".dict")
+    val tool = new CollectAlternateContigNames(
+      input                = reportHg19,
+      output               = output,
+      primary              = Column.RefSeqAccession,
+      alternates           = Seq(Column.UcscName),
+      sortBySequencingRole = true
+    )
+    executeFgbioTool(tool)
+
+    val dict = SequenceDictionary(output)
+    dict should have length 93
+    dict.head.name shouldBe "NC_000001.10"
+    dict.head.aliases should contain theSameElementsInOrderAs Seq("chr1")
+    dict.last.name shouldBe "NT_167243.1"
+    dict.last.aliases should contain theSameElementsInOrderAs Seq("chrUn_gl000249")
+    dict.map(m => m(Column.SequenceRole.tag)).toIndexedSeq.distinct should contain theSameElementsInOrderAs Seq(AssembledMolecule, AltScaffold, UnlocalizedScaffold, UnplacedScaffold).map(_.key)
+  }
 }