feat: Add additional parameters and validator for regulatory element (#336)

closes #335

Author: jarbesfeld

src/fusor/fusor.py

@@ -38,6 +38,7 @@
     Fusion,
     FusionType,
     GeneElement,
+    GenomicLocation,
     InternalTandemDuplication,
     InternalTandemDuplicationElements,
     LinkerElement,
@@ -524,26 +525,75 @@ def regulatory_element(
         self,
         regulatory_class: RegulatoryClass,
         gene: str,
+        feature_id: str | None = None,
+        sequence_id: str | None = None,
+        start: int | None = None,
+        end: int | None = None,
+        seq_id_target_namespace: str | None = None,
+        coordinate_type: CoordinateType = CoordinateType.RESIDUE,
         use_minimal_gene: bool = True,
     ) -> tuple[RegulatoryElement | None, str | None]:
         """Create RegulatoryElement
 
         :param regulatory_class: one of {"promoter", "enhancer"}
         :param gene: gene term to fetch normalized gene object for
+        :param feature_id: The feature ID for the regulatory element
+        :param sequence_id: Genomic sequence on which provided coordinates exist
+        :param start: Start position on sequence
+        :param end: Etart position on sequence
+        :param seq_id_target_namespace: If want to use digest for
+            ``sequence_id``, set this to the namespace you want the digest for.
+              Otherwise, leave as ``None``.
+        :param coordinate_type: The coordinate type that is being supplied
+            for ``start`` and ``end``. This is set to residue coordinates
+            by default
         :param use_minimal_gene: whether to use the minimal gene object
-        :return: Tuple with RegulatoryElement instance and None value for warnings if
-            successful, or a None value and warning message if unsuccessful
+        :return: Tuple with RegulatoryElement instance and None value for
+            warnings if successful, or a None value and warning message if
+            unsuccessful
         """
         gene_descr, warning = self._normalized_gene(
             gene, use_minimal_gene=use_minimal_gene
         )
         if not gene_descr:
             return None, warning
 
+        if coordinate_type == CoordinateType.RESIDUE:
+            if start == 0:
+                return (
+                    None,
+                    "start must exceed 0 if using residue coordinates to construct the feature_location",
+                )
+            if end == 0:
+                return (
+                    None,
+                    "end must exceed 0 if using residue coordinates to construct the feature_location",
+                )
+
+        use_feat_location = any(loc_var for loc_var in (sequence_id, start, end))
+        if use_feat_location:
+            if not sequence_id or not start or not end:
+                return (
+                    None,
+                    "sequence_id, start, and end must all be provided to construct the feature_location",
+                )
+            feat_location = self._sequence_location(
+                start - 1 if coordinate_type == CoordinateType.RESIDUE else start,
+                end,
+                sequence_id,
+                seq_id_target_namespace=seq_id_target_namespace,
+            )
+            feat_location = GenomicLocation(
+                **feat_location.model_dump(exclude="name"), name=sequence_id
+            )
+
         try:
             return (
                 RegulatoryElement(
-                    regulatoryClass=regulatory_class, associatedGene=gene_descr
+                    regulatoryClass=regulatory_class,
+                    associatedGene=gene_descr,
+                    featureId=feature_id,
+                    featureLocation=feat_location if use_feat_location else None,
                 ),
                 None,
             )

src/fusor/models.py

@@ -22,6 +22,7 @@
     StrictInt,
     StrictStr,
     StringConstraints,
+    field_validator,
     model_validator,
 )
 
@@ -59,6 +60,41 @@ class FUSORTypes(str, Enum):
     CAUSATIVE_EVENT = "CausativeEvent"
 
 
+class GenomicLocation(SequenceLocation):
+    """Define GenomicLocation class"""
+
+    name: str
+
+    @field_validator("name")
+    def validate_genomic_location(cls, value: str):
+        """Validate that featureLocation only describes genomic coordinates
+        if provided
+
+        :param value: The value for `name`
+        :raises ValueError: If a non-chromosomal accession are provided to
+            `name`
+        """
+        if not value.startswith("NC_"):
+            msg = "`name` must be a RefSeq chromosomal accession that starts with `NC_`"
+            raise ValueError(msg)
+        return value
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "ga4gh:SL.9hqdPDfXC-m_t_bDH75FZHfaM6OKDtRw",
+                "name": "NC_000001.11",
+                "type": "SequenceLocation",
+                "sequenceReference": {
+                    "refgetAccession": "SQ.Ya6Rs7DHhDeg7YaOSg1EoNi3U_nQ9SvO",
+                },
+                "start": 155593,
+                "end": 155610,
+            }
+        },
+    )
+
+
 class AdditionalFields(str, Enum):
     """Define possible fields that can be added to Fusion object."""
 
@@ -500,7 +536,7 @@ class RegulatoryElement(BaseModel):
     regulatoryClass: RegulatoryClass
     featureId: str | None = None
     associatedGene: MappableConcept | None = None
-    featureLocation: SequenceLocation | None = None
+    featureLocation: GenomicLocation | None = None
 
     @model_validator(mode="after")
     def ensure_min_values(cls, values):
@@ -523,6 +559,7 @@ def ensure_min_values(cls, values):
                 "regulatoryClass": "promoter",
                 "featureLocation": {
                     "id": "ga4gh:SL.9hqdPDfXC-m_t_bDH75FZHfaM6OKDtRw",
+                    "name": "NC_000001.11",
                     "type": "SequenceLocation",
                     "sequenceReference": {
                         "id": "refseq:NC_000001.11",

tests/test_fusor.py

@@ -13,6 +13,7 @@
     CategoricalFusion,
     FunctionalDomain,
     GeneElement,
+    GenomicLocation,
     InternalTandemDuplication,
     LinkerElement,
     MultiplePossibleGenesElement,
@@ -38,6 +39,20 @@ def braf_gene_obj_min():
     )
 
 
+@pytest.fixture(scope="module")
+def tpm3_gene_obj_min():
+    """Create minimal gene object for TPM3"""
+    return MappableConcept(
+        primaryCoding=Coding(
+            id="hgnc:12012",
+            code="HGNC:12012",
+            system="https://www.genenames.org/data/gene-symbol-report/#!/hgnc_id/",
+        ),
+        name="TPM3",
+        conceptType="Gene",
+    )
+
+
 @pytest.fixture(scope="module")
 def braf_gene_obj(braf_gene):
     """Create gene object for braf"""
@@ -142,6 +157,38 @@ def regulatory_element(braf_gene_obj):
     return RegulatoryElement(**params)
 
 
+@pytest.fixture(scope="module")
+def genomic_location_feature_location():
+    """Create test genomic location for feature location. Adapted from models.py"""
+    params = {
+        "id": "ga4gh:SL.-xC3omZDIKZEuotbbHWQMTC8sS3nOxTb",
+        "name": "NC_000001.11",
+        "type": "SequenceLocation",
+        "sequenceReference": {
+            "id": "refseq:NC_000001.11",
+            "refgetAccession": "SQ.Ya6Rs7DHhDeg7YaOSg1EoNi3U_nQ9SvO",
+            "type": "SequenceReference",
+        },
+        "start": 15455,
+        "end": 15456,
+        "extensions": [{"name": "is_exonic", "value": True}],
+    }
+    return GenomicLocation(**params)
+
+
+@pytest.fixture(scope="module")
+def regulatory_element_full(tpm3_gene_obj_min, genomic_location_feature_location):
+    """Create full regulatory element test fixture"""
+    params = {
+        "type": "RegulatoryElement",
+        "regulatoryClass": "enhancer",
+        "associatedGene": tpm3_gene_obj_min,
+        "featureID": "EH12345",
+        "featureLocation": genomic_location_feature_location,
+    }
+    return RegulatoryElement(**params)
+
+
 @pytest.fixture(scope="module")
 def regulatory_element_min(braf_gene_obj_min):
     """Create regulatory element test fixture with minimal gene object."""
@@ -848,7 +895,9 @@ def compare_domains(actual, expected):
     )
 
 
-def test_regulatory_element(fusor_instance, regulatory_element, regulatory_element_min):
+def test_regulatory_element(
+    fusor_instance, regulatory_element, regulatory_element_min, regulatory_element_full
+):
     """Test regulatory_element method."""
 
     def compare_re(actual, expected):
@@ -860,9 +909,78 @@ def compare_re(actual, expected):
         assert actual.keys() == expected.keys()
         assert actual["type"] == expected["type"]
         compare_gene_obj(actual["associatedGene"], expected["associatedGene"])
-
-    re = fusor_instance.regulatory_element(RegulatoryClass.PROMOTER, "BRAF")
+        if actual.get("featureID"):
+            assert actual["featureID"] == expected["featureID"]
+        if actual.get("featureLocation"):
+            assert actual["featureLocation"]["id"] == expected["featureLocation"]["id"]
+            assert (
+                actual["featureLocation"]["start"]
+                == expected["featureLocation"]["start"]
+            )
+            assert (
+                actual["featureLocation"]["end"] == expected["featureLocation"]["end"]
+            )
+
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.PROMOTER,
+        gene="BRAF",
+    )
     compare_re(re, regulatory_element_min)
 
-    re = fusor_instance.regulatory_element(RegulatoryClass.PROMOTER, "BRAF", False)
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.PROMOTER, gene="BRAF", use_minimal_gene=False
+    )
     compare_re(re, regulatory_element)
+
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.ENHANCER,
+        gene="TPM3",
+        feature_id="EH12345",
+        sequence_id="NC_000001.11",
+        start=15455,
+        end=15456,
+        coordinate_type=CoordinateType.INTER_RESIDUE,
+    )
+    compare_re(re, regulatory_element_full)
+
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.ENHANCER,
+        gene="TPM3",
+        feature_id="EH12345",
+        sequence_id="NC_000001.11",
+        start=15455,
+        coordinate_type=CoordinateType.INTER_RESIDUE,
+    )
+    assert re[0] is None
+    assert (
+        re[1]
+        == "sequence_id, start, and end must all be provided to construct the feature_location"
+    )
+
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.ENHANCER,
+        gene="TPM3",
+        feature_id="EH12345",
+        sequence_id="NC_000001.11",
+        start=0,
+        coordinate_type=CoordinateType.RESIDUE,
+    )
+    assert re[0] is None
+    assert (
+        re[1]
+        == "start must exceed 0 if using residue coordinates to construct the feature_location"
+    )
+
+    re = fusor_instance.regulatory_element(
+        regulatory_class=RegulatoryClass.ENHANCER,
+        gene="TPM3",
+        feature_id="EH12345",
+        sequence_id="NC_000001.11",
+        end=0,
+        coordinate_type=CoordinateType.RESIDUE,
+    )
+    assert re[0] is None
+    assert (
+        re[1]
+        == "end must exceed 0 if using residue coordinates to construct the feature_location"
+    )

tests/test_models.py

@@ -176,6 +176,7 @@ def sequence_locations():
         {
             "id": "ga4gh:SL.VJLxl42yYoa-0ZMa8dfakhZfcP0nWgpl",
             "type": "SequenceLocation",
+            "name": "NP_001123617.1",
             "sequenceReference": {
                 "id": "refseq:NP_001123617.1",
                 "refgetAccession": "SQ.sv5egNzqN5koJQH6w0M4tIK9tEDEfJl7",
@@ -776,7 +777,7 @@ def test_event():
         CausativeEvent(eventType="combination")
 
 
-def test_regulatory_element(regulatory_elements, gene_examples):
+def test_regulatory_element(regulatory_elements, gene_examples, sequence_locations):
     """Test RegulatoryElement object initializes correctly"""
     test_reg_elmt = RegulatoryElement(**regulatory_elements[0])
     assert test_reg_elmt.regulatoryClass.value == "promoter"
@@ -798,6 +799,18 @@ def test_regulatory_element(regulatory_elements, gene_examples):
         == "Value error, Must set 1 of {`featureId`, `associatedGene`} and/or `featureLocation`"
     )
 
+    # Require chromosomal build
+    with pytest.raises(ValidationError) as exc_info:
+        RegulatoryElement(
+            regulatoryClass="enhancer",
+            associatedGene=gene_examples[0],
+            featureLocation=sequence_locations[6],
+        )
+    assert (
+        exc_info.value.errors()[0]["msg"]
+        == "Value error, `name` must be a RefSeq chromosomal accession that starts with `NC_`"
+    )
+
 
 def test_fusion_itd(
     functional_domains,

tests/test_nomenclature.py

@@ -73,6 +73,7 @@ def reg_location_example():
             },
             "featureLocation": {
                 "type": "SequenceLocation",
+                "name": "NC_000023.11",
                 "id": "ga4gh:SL.KMHXvX8m5fD8PcGlQu2Vja3m7bt2iqfK",
                 "sequenceReference": {
                     "id": "refseq:NC_000023.11",