feat(genomics): Refactor coverage handling with embedded JSONB in alignment metadata

- Removed `AlignmentCoverage` model and related Slick table (`AlignmentCoverageTable`).
- Introduced `EmbeddedCoverage` for compact JSONB-based coverage representation directly on `AlignmentMetadata`.
- Refactored `AlignmentRepository` and `CoverageRepository` to support new JSONB structure for coverage updates and queries.
- Optimized SQL queries and benchmarks to utilize JSONB fields for coverage data.
- Added unit tests for `EmbeddedCoverage` serialization, deserialization, and integration validation across repositories.

Author: JamesKane

app/models/dal/DatabaseSchema.scala

@@ -63,7 +63,7 @@ object DatabaseSchema {
       val analysisMethods = TableQuery[AnalysisMethodTable]
       val ancestryAnalyses = TableQuery[AncestryAnalysisTable]
       val alignmentMetadata = TableQuery[AlignmentMetadataTable]
-      val alignmentCoverages = TableQuery[AlignmentCoverageTable]
+
       val assemblyMetadata = TableQuery[AssemblyMetadataTable]
       val biosampleHaplogroups = TableQuery[BiosampleHaplogroupsTable]
       val biosamples = TableQuery[BiosamplesTable]

app/models/dal/domain/genomics/AlignmentCoverageTable.scala

@@ -61,25 +61,27 @@ class AlignmentMetadataTable(tag: Tag) extends Table[AlignmentMetadata](tag, Som
 
   def metadata = column[Option[JsValue]]("metadata")
 
+  def coverage = column[Option[JsValue]]("coverage")
+
   def * = (
     (id.?, sequenceFileId, genbankContigId, metricLevel),
     (regionName, regionStartPos, regionEndPos, regionLengthBp),
     (referenceBuild, variantCaller, genomeTerritory, meanCoverage, medianCoverage, sdCoverage, pctExcDupe, pctExcMapq, pct10x, pct20x, pct30x, hetSnpSensitivity),
-    (metricsDate, analysisTool, analysisToolVersion, notes, metadata)
+    (metricsDate, analysisTool, analysisToolVersion, notes, metadata, coverage)
   ).shaped <> ( {
-    case ((id, seqId, contigId, lvl), (rName, rStart, rEnd, rLen), (refBuild, vCaller, gTerr, meanCov, medCov, sdCov, pDupe, pMapq, p10, p20, p30, hetSens), (mDate, tool, toolVer, notes, meta)) =>
+    case ((id, seqId, contigId, lvl), (rName, rStart, rEnd, rLen), (refBuild, vCaller, gTerr, meanCov, medCov, sdCov, pDupe, pMapq, p10, p20, p30, hetSens), (mDate, tool, toolVer, notes, meta, cov)) =>
       AlignmentMetadata(
         id, seqId, contigId, lvl,
         rName, rStart, rEnd, rLen,
         refBuild, vCaller, gTerr, meanCov, medCov, sdCov, pDupe, pMapq, p10, p20, p30, hetSens,
-        mDate, tool, toolVer, notes, meta
+        mDate, tool, toolVer, notes, meta, cov
       )
   }, { (m: AlignmentMetadata) =>
     Some((
       (m.id, m.sequenceFileId, m.genbankContigId, m.metricLevel),
       (m.regionName, m.regionStartPos, m.regionEndPos, m.regionLengthBp),
       (m.referenceBuild, m.variantCaller, m.genomeTerritory, m.meanCoverage, m.medianCoverage, m.sdCoverage, m.pctExcDupe, m.pctExcMapq, m.pct10x, m.pct20x, m.pct30x, m.hetSnpSensitivity),
-      (m.metricsDate, m.analysisTool, m.analysisToolVersion, m.notes, m.metadata)
+      (m.metricsDate, m.analysisTool, m.analysisToolVersion, m.notes, m.metadata, m.coverage)
     ))
   }
   )

app/models/dal/domain/genomics/AlignmentMetadataTable.scala

@@ -75,9 +75,33 @@ case class AlignmentMetadata(
                               analysisTool: String,
                               analysisToolVersion: Option[String] = None,
                               notes: Option[String] = None,
-                              metadata: Option[JsValue] = None
-                            )
+                              metadata: Option[JsValue] = None,
+                              coverage: Option[JsValue] = None
+                            ) {
+
+  def embeddedCoverage: Option[EmbeddedCoverage] = coverage.flatMap(_.asOpt[EmbeddedCoverage])
+
+  def withCoverage(ec: EmbeddedCoverage): AlignmentMetadata = copy(coverage = Some(Json.toJson(ec)))
+}
 
 object AlignmentMetadata {
   implicit val format: OFormat[AlignmentMetadata] = Json.format[AlignmentMetadata]
+}
+
+case class EmbeddedCoverage(
+                             meanDepth: Option[Double] = None,
+                             medianDepth: Option[Double] = None,
+                             percentCoverageAt1x: Option[Double] = None,
+                             percentCoverageAt5x: Option[Double] = None,
+                             percentCoverageAt10x: Option[Double] = None,
+                             percentCoverageAt20x: Option[Double] = None,
+                             percentCoverageAt30x: Option[Double] = None,
+                             basesNoCoverage: Option[Long] = None,
+                             basesLowQualityMapping: Option[Long] = None,
+                             basesCallable: Option[Long] = None,
+                             meanMappingQuality: Option[Double] = None
+                           )
+
+object EmbeddedCoverage {
+  implicit val format: OFormat[EmbeddedCoverage] = Json.format[EmbeddedCoverage]
 }

app/models/domain/genomics/AlignmentCoverage.scala

@@ -2,80 +2,30 @@ package repositories
 
 import jakarta.inject.{Inject, Singleton}
 import models.dal.DatabaseSchema
-import models.domain.genomics.{AlignmentCoverage, AlignmentMetadata, MetricLevel}
+import models.domain.genomics.{AlignmentMetadata, EmbeddedCoverage, MetricLevel}
 import play.api.db.slick.DatabaseConfigProvider
+import play.api.libs.json.Json
 
 import scala.concurrent.{ExecutionContext, Future}
 
 /**
  * Repository interface for managing alignment metadata and coverage statistics.
  */
 trait AlignmentRepository {
-  /**
-   * Creates a new alignment metadata record.
-   *
-   * @param metadata The alignment metadata to create
-   * @return A future containing the created metadata with its assigned ID
-   */
   def createMetadata(metadata: AlignmentMetadata): Future[AlignmentMetadata]
 
-  /**
-   * Creates or updates coverage statistics for an alignment.
-   *
-   * @param coverage The coverage statistics to upsert
-   * @return A future containing the upserted coverage record
-   */
-  def upsertCoverage(coverage: AlignmentCoverage): Future[AlignmentCoverage]
-
-  /**
-   * Finds all alignment metadata for a specific sequence file.
-   *
-   * @param sequenceFileId The sequence file ID
-   * @return A future containing a sequence of alignment metadata records
-   */
+  def updateCoverage(metadataId: Long, coverage: EmbeddedCoverage): Future[Boolean]
+
   def findMetadataBySequenceFile(sequenceFileId: Long): Future[Seq[AlignmentMetadata]]
 
-  /**
-   * Finds alignment metadata for a specific contig.
-   *
-   * @param genbankContigId The GenBank contig ID
-   * @param metricLevel     Optional filter by metric level
-   * @return A future containing a sequence of alignment metadata records
-   */
   def findMetadataByContig(genbankContigId: Int, metricLevel: Option[MetricLevel] = None): Future[Seq[AlignmentMetadata]]
 
-  /**
-   * Retrieves alignment metadata with associated coverage statistics.
-   *
-   * @param metadataId The alignment metadata ID
-   * @return A future containing an optional tuple of (metadata, coverage)
-   */
-  def findMetadataWithCoverage(metadataId: Long): Future[Option[(AlignmentMetadata, Option[AlignmentCoverage])]]
-
-  /**
-   * Finds all alignment metadata and coverage for a sequence file.
-   *
-   * @param sequenceFileId The sequence file ID
-   * @return A future containing a sequence of tuples (metadata, coverage)
-   */
-  def findAllWithCoverageBySequenceFile(sequenceFileId: Long): Future[Seq[(AlignmentMetadata, Option[AlignmentCoverage])]]
-
-  /**
-   * Deletes alignment metadata and associated coverage by ID.
-   *
-   * @param metadataId The alignment metadata ID to delete
-   * @return A future containing the number of deleted records
-   */
+  def findMetadataById(metadataId: Long): Future[Option[AlignmentMetadata]]
+
+  def findAllBySequenceFile(sequenceFileId: Long): Future[Seq[AlignmentMetadata]]
+
   def deleteMetadata(metadataId: Long): Future[Int]
 
-  /**
-   * Finds regional alignment statistics for a specific genomic region.
-   *
-   * @param genbankContigId The GenBank contig ID
-   * @param startPos        Start position (1-based, inclusive)
-   * @param endPos          End position (1-based, inclusive)
-   * @return A future containing a sequence of regional alignment metadata
-   */
   def findRegionalMetadata(genbankContigId: Int, startPos: Long, endPos: Long): Future[Seq[AlignmentMetadata]]
 }
 
@@ -89,7 +39,6 @@ class AlignmentRepositoryImpl @Inject()(
   import models.dal.MyPostgresProfile.api.*
 
   private val metadataTable = DatabaseSchema.domain.genomics.alignmentMetadata
-  private val coverageTable = DatabaseSchema.domain.genomics.alignmentCoverages
 
   override def createMetadata(metadata: AlignmentMetadata): Future[AlignmentMetadata] = {
     val insertQuery = (metadataTable returning metadataTable.map(_.id)
@@ -99,12 +48,12 @@ class AlignmentRepositoryImpl @Inject()(
     db.run(insertQuery.transactionally)
   }
 
-  override def upsertCoverage(coverage: AlignmentCoverage): Future[AlignmentCoverage] = {
+  override def updateCoverage(metadataId: Long, coverage: EmbeddedCoverage): Future[Boolean] = {
     db.run(
-      coverageTable.insertOrUpdate(coverage)
-        .map(_ => coverage)
-        .transactionally
-    )
+      metadataTable.filter(_.id === metadataId)
+        .map(_.coverage)
+        .update(Some(Json.toJson(coverage)))
+    ).map(_ > 0)
   }
 
   override def findMetadataBySequenceFile(sequenceFileId: Long): Future[Seq[AlignmentMetadata]] = {
@@ -125,23 +74,19 @@ class AlignmentRepositoryImpl @Inject()(
     db.run(filteredQuery.result)
   }
 
-  override def findMetadataWithCoverage(metadataId: Long): Future[Option[(AlignmentMetadata, Option[AlignmentCoverage])]] = {
+  override def findMetadataById(metadataId: Long): Future[Option[AlignmentMetadata]] = {
     db.run(
       metadataTable
         .filter(_.id === metadataId)
-        .joinLeft(coverageTable)
-        .on(_.id === _.alignmentMetadataId)
         .result
         .headOption
     )
   }
 
-  override def findAllWithCoverageBySequenceFile(sequenceFileId: Long): Future[Seq[(AlignmentMetadata, Option[AlignmentCoverage])]] = {
+  override def findAllBySequenceFile(sequenceFileId: Long): Future[Seq[AlignmentMetadata]] = {
     db.run(
       metadataTable
         .filter(_.sequenceFileId === sequenceFileId)
-        .joinLeft(coverageTable)
-        .on(_.id === _.alignmentMetadataId)
         .result
     )
   }
@@ -168,4 +113,4 @@ class AlignmentRepositoryImpl @Inject()(
         .result
     )
   }
-}
+}