feat: add mapped hgnc name to target genes table, set in mapping job and update related structures

Author: bencap

alembic/versions/dcf8572d3a17_add_mapped_hgnc_name_to_targets.py

@@ -0,0 +1,29 @@
+"""add mapped hgnc name to targets
+
+Revision ID: dcf8572d3a17
+Revises: b22b450d409c
+Create Date: 2025-12-12 17:32:40.147429
+
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "dcf8572d3a17"
+down_revision = "b22b450d409c"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column("target_genes", sa.Column("mapped_hgnc_name", sa.String(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("target_genes", "mapped_hgnc_name")
+    # ### end Alembic commands ###

src/mavedb/lib/mapping.py

@@ -13,11 +13,19 @@
 class VRSMap:
     url: str
 
+    class GeneInfo(TypedDict):
+        hgnc_symbol: str
+        selection_method: str
+
+    class TargetAnnotation(TypedDict):
+        gene_info: "VRSMap.GeneInfo"
+        layers: dict[str, dict[str, dict[str, dict[str, Union[str, list[str]]]]]]
+
     class ScoreSetMappingResults(TypedDict):
         metadata: Optional[dict[str, str]]
         dcd_mapping_version: str
         mapped_date_utc: date
-        reference_sequences: Optional[dict[str, dict[str, dict[str, dict[str, Union[str, list[str]]]]]]]
+        reference_sequences: Optional[dict[str, "VRSMap.TargetAnnotation"]]
         mapped_scores: Optional[list[dict]]
         error_message: Optional[str]
 

src/mavedb/models/target_gene.py

@@ -47,6 +47,7 @@ class TargetGene(Base):
 
     pre_mapped_metadata: Mapped[JSONB] = Column("pre_mapped_metadata", JSONB, nullable=True)
     post_mapped_metadata: Mapped[JSONB] = Column("post_mapped_metadata", JSONB, nullable=True)
+    mapped_hgnc_name = Column(String, nullable=True)
     uniprot_id_from_mapped_metadata = Column(String, nullable=True)
 
     creation_date = Column(Date, nullable=False, default=date.today)

src/mavedb/view_models/target_gene.py

@@ -60,6 +60,7 @@ class SavedTargetGene(TargetGeneBase):
     target_sequence: Optional[SavedTargetSequence] = None
     target_accession: Optional[SavedTargetAccession] = None
     external_identifiers: Sequence[external_gene_identifier_offset.SavedExternalGeneIdentifierOffset]
+    mapped_hgnc_name: Optional[str] = None
     uniprot_id_from_mapped_metadata: Optional[str] = None
 
     _record_type_factory = record_type_validator()(set_record_type)

src/mavedb/worker/jobs.py

@@ -453,10 +453,15 @@ async def map_variants_for_score_set(
                                 f"Target gene {target_gene_identifier} not found in database for score set {score_set.urn}."
                             )
                         # allow for multiple annotation layers
-                        pre_mapped_metadata = {}
-                        post_mapped_metadata = {}
+                        pre_mapped_metadata: dict[str, Any] = {}
+                        post_mapped_metadata: dict[str, Any] = {}
                         excluded_pre_mapped_keys = {"sequence"}
-                        post_mapped_metadata["gene_info"] = reference_metadata[target_gene_identifier].get("gene_info")
+
+                        gene_info = reference_metadata[target_gene_identifier].get("gene_info")
+                        if gene_info:
+                            target_gene.mapped_hgnc_name = gene_info.get("hgnc_symbol")
+                            post_mapped_metadata["hgnc_name_selection_method"] = gene_info.get("selection_method")
+
                         for annotation_layer in reference_metadata[target_gene_identifier]["layers"]:
                             layer_premapped = reference_metadata[target_gene_identifier]["layers"][
                                 annotation_layer