cool-seq-tool 0.4.0.dev2__py3-none-any.whl → 0.4.1__py3-none-any.whl

cool_seq_tool/mappers/exon_genomic_coords.py

@@ -1,7 +1,9 @@
 """Provide mapping capabilities between transcript exon and genomic coordinates."""
+
 import logging
-from typing import Dict, List, Optional, Tuple, TypeVar, Union
+from typing import Literal, TypeVar
 
+from cool_seq_tool.handlers.seqrepo_access import SeqRepoAccess
 from cool_seq_tool.mappers.mane_transcript import CdnaRepresentation, ManeTranscript
 from cool_seq_tool.schemas import (
     AnnotationLayer,
@@ -13,6 +15,7 @@ from cool_seq_tool.schemas import (
     TranscriptExonData,
     TranscriptExonDataResponse,
 )
+from cool_seq_tool.sources.mane_transcript_mappings import ManeTranscriptMappings
 from cool_seq_tool.sources.uta_database import UtaDatabase
 from cool_seq_tool.utils import get_inter_residue_pos, service_meta
 
@@ -28,7 +31,13 @@ class ExonGenomicCoordsMapper:
     coordinate representation.
     """
 
-    def __init__(self, uta_db: UtaDatabase, mane_transcript: ManeTranscript) -> None:
+    def __init__(
+        self,
+        seqrepo_access: SeqRepoAccess,
+        uta_db: UtaDatabase,
+        mane_transcript: ManeTranscript,
+        mane_transcript_mappings: ManeTranscriptMappings,
+    ) -> None:
         """Initialize ExonGenomicCoordsMapper class.
 
         A lot of resources are required for initialization, so when defaults are enough,
@@ -42,19 +51,23 @@ class ExonGenomicCoordsMapper:
         event loop. See the :ref:`Usage section <async_note>` for more information.
 
         >>> import asyncio
-        >>> result = asyncio.run(egc.transcript_to_genomic_coordinates(
-        ...     "NM_002529.3",
-        ...     exon_start=2,
-        ...     exon_end=17
-        ... ))
+        >>> result = asyncio.run(
+        ...     egc.transcript_to_genomic_coordinates(
+        ...         "NM_002529.3", exon_start=2, exon_end=17
+        ...     )
+        ... )
         >>> result.genomic_data.start, result.genomic_data.end
         (156864428, 156881456)
 
+        :param seqrepo_access: SeqRepo instance to give access to query SeqRepo database
         :param uta_db: UtaDatabase instance to give access to query UTA database
         :param mane_transcript: Instance to align to MANE or compatible representation
+        :param mane_transcript_mappings: Instance to provide access to ManeTranscriptMappings class
         """
+        self.seqrepo_access = seqrepo_access
         self.uta_db = uta_db
         self.mane_transcript = mane_transcript
+        self.mane_transcript_mappings = mane_transcript_mappings
 
     @staticmethod
     def _return_warnings(
@@ -74,10 +87,10 @@ class ExonGenomicCoordsMapper:
     async def transcript_to_genomic_coordinates(
         self,
         transcript: str,
-        gene: Optional[str] = None,
-        exon_start: Optional[int] = None,
+        gene: str | None = None,
+        exon_start: int | None = None,
         exon_start_offset: int = 0,
-        exon_end: Optional[int] = None,
+        exon_end: int | None = None,
         exon_end_offset: int = 0,
     ) -> GenomicDataResponse:
         """Get genomic data given transcript data.
@@ -87,11 +100,14 @@ class ExonGenomicCoordsMapper:
         >>> import asyncio
         >>> from cool_seq_tool.app import CoolSeqTool
         >>> egc = CoolSeqTool().ex_g_coords_mapper
-        >>> tpm3 = asyncio.run(egc.transcript_to_genomic_coordinates(
-        ...     "NM_152263.3"
-        ...     gene="TPM3", chr="NC_000001.11",
-        ...     exon_start=1, exon_end=8,
-        ... ))
+        >>> tpm3 = asyncio.run(
+        ...     egc.transcript_to_genomic_coordinates(
+        ...         "NM_152263.3",
+        ...         gene="TPM3",
+        ...         exon_start=1,
+        ...         exon_end=8,
+        ...     )
+        ... )
         >>> tpm3.genomic_data.chr, tpm3.genomic_data.start, tpm3.genomic_data.end
         ('NC_000001.11', 154192135, 154170399)
 
@@ -211,16 +227,16 @@ class ExonGenomicCoordsMapper:
 
     async def genomic_to_transcript_exon_coordinates(
         self,
-        chromosome: Optional[str] = None,
-        alt_ac: Optional[str] = None,
-        start: Optional[int] = None,
-        end: Optional[int] = None,
-        strand: Optional[Strand] = None,
-        transcript: Optional[str] = None,
-        gene: Optional[str] = None,
-        residue_mode: Union[
-            ResidueMode.INTER_RESIDUE, ResidueMode.RESIDUE
-        ] = ResidueMode.RESIDUE,
+        chromosome: str | None = None,
+        alt_ac: str | None = None,
+        start: int | None = None,
+        end: int | None = None,
+        strand: Strand | None = None,
+        transcript: str | None = None,
+        get_nearest_transcript_junction: bool = False,
+        gene: str | None = None,
+        residue_mode: Literal[ResidueMode.INTER_RESIDUE]
+        | Literal[ResidueMode.RESIDUE] = ResidueMode.RESIDUE,
     ) -> GenomicDataResponse:
         """Get transcript data for genomic data, lifted over to GRCh38.
 
@@ -231,13 +247,15 @@ class ExonGenomicCoordsMapper:
         >>> from cool_seq_tool.app import CoolSeqTool
         >>> from cool_seq_tool.schemas import Strand
         >>> egc = CoolSeqTool().ex_g_coords_mapper
-        >>> result = asyncio.run(egc.genomic_to_transcript_exon_coordinates(
-        ...     chromosome="NC_000001.11",
-        ...     start=154192136,
-        ...     end=154170400,
-        ...     strand=Strand.NEGATIVE,
-        ...     transcript="NM_152263.3"
-        ... ))
+        >>> result = asyncio.run(
+        ...     egc.genomic_to_transcript_exon_coordinates(
+        ...         alt_ac="NC_000001.11",
+        ...         start=154192136,
+        ...         end=154170400,
+        ...         strand=Strand.NEGATIVE,
+        ...         transcript="NM_152263.3",
+        ...     )
+        ... )
         >>> result.genomic_data.exon_start, result.genomic_data.exon_end
         (1, 8)
 
@@ -254,7 +272,13 @@ class ExonGenomicCoordsMapper:
             following transcripts: MANE Select, MANE Clinical Plus, Longest Remaining
             Compatible Transcript. See the :ref:`Transcript Selection policy <transcript_selection_policy>`
             page.
-        :param gene: HGNC gene symbol
+        :param get_nearest_transcript_junction: If ``True``, this will return the
+            adjacent exon if the position specified by``start`` or ``end`` does not
+            occur on an exon. For the positive strand, adjacent is defined as the exon
+            preceding the breakpoint for the 5' end and the exon following the
+            breakpoint for the 3' end. For the negative strand, adjacent is defined as
+            the exon following the breakpoint for the 5' end and the exon preceding the
+            breakpoint for the 3' end.
         :param residue_mode: Residue mode for ``start`` and ``end``
         :return: Genomic data (inter-residue coordinates)
         """
@@ -280,6 +304,7 @@ class ExonGenomicCoordsMapper:
                 strand=strand,
                 transcript=transcript,
                 gene=gene,
+                get_nearest_transcript_junction=get_nearest_transcript_junction,
                 is_start=True,
             )
             if start_data.transcript_exon_data:
@@ -299,6 +324,7 @@ class ExonGenomicCoordsMapper:
                 strand=strand,
                 transcript=transcript,
                 gene=gene,
+                get_nearest_transcript_junction=get_nearest_transcript_junction,
                 is_start=False,
             )
             if end_data.transcript_exon_data:
@@ -337,8 +363,8 @@ class ExonGenomicCoordsMapper:
 
     @staticmethod
     def _validate_exon(
-        transcript: str, tx_exons: List[Tuple[int, int]], exon_number: int
-    ) -> Tuple[Optional[Tuple[int, int]], Optional[str]]:
+        transcript: str, tx_exons: list[tuple[int, int]], exon_number: int
+    ) -> tuple[tuple[int, int] | None, str | None]:
         """Validate that exon number exists on a given transcript
 
         :param transcript: Transcript accession
@@ -358,12 +384,12 @@ class ExonGenomicCoordsMapper:
     def get_tx_exon_coords(
         self,
         transcript: str,
-        tx_exons: List[Tuple[int, int]],
-        exon_start: Optional[int] = None,
-        exon_end: Optional[int] = None,
-    ) -> Tuple[
-        Optional[Tuple[Optional[Tuple[int, int]], Optional[Tuple[int, int]]]],
-        Optional[str],
+        tx_exons: list[tuple[int, int]],
+        exon_start: int | None = None,
+        exon_end: int | None = None,
+    ) -> tuple[
+        tuple[tuple[int, int] | None, tuple[int, int] | None] | None,
+        str | None,
     ]:
         """Get exon coordinates for ``exon_start`` and ``exon_end``
 
@@ -394,10 +420,10 @@ class ExonGenomicCoordsMapper:
     async def _get_alt_ac_start_and_end(
         self,
         tx_ac: str,
-        tx_exon_start: Optional[Tuple[int, int]] = None,
-        tx_exon_end: Optional[Tuple[int, int]] = None,
-        gene: Optional[str] = None,
-    ) -> Tuple[Optional[Tuple[Tuple[int, int], Tuple[int, int]]], Optional[str]]:
+        tx_exon_start: tuple[int, int] | None = None,
+        tx_exon_end: tuple[int, int] | None = None,
+        gene: str | None = None,
+    ) -> tuple[tuple[tuple[int, int], tuple[int, int]] | None, str | None]:
         """Get aligned genomic coordinates for transcript exon start and end.
 
         :param tx_ac: Transcript accession
@@ -448,11 +474,12 @@ class ExonGenomicCoordsMapper:
     async def _genomic_to_transcript_exon_coordinate(
         self,
         pos: int,
-        chromosome: Optional[str] = None,
-        alt_ac: Optional[str] = None,
-        strand: Optional[Strand] = None,
-        transcript: Optional[str] = None,
-        gene: Optional[str] = None,
+        chromosome: str | None = None,
+        alt_ac: str | None = None,
+        strand: Strand | None = None,
+        transcript: str | None = None,
+        gene: str | None = None,
+        get_nearest_transcript_junction: bool = False,
         is_start: bool = True,
     ) -> TranscriptExonDataResponse:
         """Convert individual genomic data to transcript data
@@ -469,6 +496,13 @@ class ExonGenomicCoordsMapper:
             following transcripts: MANE Select, MANE Clinical Plus, Longest Remaining
             Compatible Transcript
         :param gene: HGNC gene symbol
+        :param get_nearest_transcript_junction: If ``True``, this will return the
+            adjacent exon if the position specified by``start`` or ``end`` does not
+            occur on an exon. For the positive strand, adjacent is defined as the exon
+            preceding the breakpoint for the 5' end and the exon following the
+            breakpoint for the 3' end. For the negative strand, adjacent is defined as
+            the exon following the breakpoint for the 5' end and the exon preceding the
+            breakpoint for the 3' end.
         :param is_start: ``True`` if ``pos`` is start position. ``False`` if ``pos`` is
             end position.
         :return: Transcript data (inter-residue coordinates)
@@ -484,6 +518,87 @@ class ExonGenomicCoordsMapper:
 
         params = {key: None for key in TranscriptExonData.model_fields}
 
+        if get_nearest_transcript_junction:
+            if not gene or not strand:
+                return self._return_warnings(
+                    resp,
+                    "Gene or strand must be provided to select the adjacent transcript junction",
+                )
+            alt_acs, w = self.seqrepo_access.chromosome_to_acs(chromosome)
+
+            if not alt_acs:
+                return self._return_warnings(resp, w)
+            alt_ac = alt_acs[0]
+
+            if not transcript:
+                # Select a transcript if not provided
+                mane_transcripts = self.mane_transcript_mappings.get_gene_mane_data(
+                    gene
+                )
+
+                if mane_transcripts:
+                    transcript = mane_transcripts[0]["RefSeq_nuc"]
+                else:
+                    # Attempt to find a coding transcript if a MANE transcript
+                    # cannot be found
+                    results = await self.uta_db.get_transcripts(
+                        gene=gene, alt_ac=alt_ac
+                    )
+
+                    if not results.is_empty():
+                        transcript = results[0]["tx_ac"][0]
+                    else:
+                        # Run if gene is for a noncoding transcript
+                        query = f"""
+                            SELECT DISTINCT tx_ac
+                            FROM {self.uta_db.schema}.tx_exon_aln_v
+                            WHERE hgnc = '{gene}'
+                            AND alt_ac = '{alt_ac}'
+                            """  # noqa: S608
+                        result = await self.uta_db.execute_query(query)
+
+                        if result:
+                            transcript = result[0]["tx_ac"]
+                        else:
+                            return self._return_warnings(
+                                resp,
+                                f"Could not find a transcript for {gene} on {alt_ac}",
+                            )
+
+            tx_genomic_coords, w = await self.uta_db.get_tx_exons_genomic_coords(
+                tx_ac=transcript, alt_ac=alt_ac
+            )
+            if not tx_genomic_coords:
+                return self._return_warnings(resp, w)
+
+            # Check if breakpoint occurs on an exon.
+            # If not, determine the adjacent exon given the selected transcript
+            if not self._is_exonic_breakpoint(pos, tx_genomic_coords):
+                exon = self._get_adjacent_exon(
+                    tx_exons_genomic_coords=tx_genomic_coords,
+                    strand=strand,
+                    start=pos if is_start else None,
+                    end=pos if not is_start else None,
+                )
+
+                params["exon"] = exon
+                params["transcript"] = transcript
+                params["gene"] = gene
+                params["pos"] = pos
+                params["chr"] = alt_ac
+
+                self._set_exon_offset(
+                    params=params,
+                    start=tx_genomic_coords[exon - 1][3],  # Start exon coordinate
+                    end=tx_genomic_coords[exon - 1][4],  # End exon coordinate
+                    pos=pos,
+                    is_start=is_start,
+                    strand=strand,
+                )
+                params["strand"] = strand.value
+                resp.transcript_exon_data = TranscriptExonData(**params)
+                return resp
+
         if alt_ac:
             # Check if valid accession is given
             if not await self.uta_db.validate_genomic_ac(alt_ac):
@@ -538,8 +653,8 @@ class ExonGenomicCoordsMapper:
 
     @staticmethod
     def _get_gene_and_alt_ac(
-        genes_alt_acs: Dict, gene: Optional[str]
-    ) -> Tuple[Optional[Tuple[str, str]], Optional[str]]:
+        genes_alt_acs: dict, gene: str | None
+    ) -> tuple[tuple[str, str] | None, str | None]:
         """Return gene genomic accession
 
         :param genes_alt_acs: Dictionary containing genes and genomic accessions
@@ -577,13 +692,13 @@ class ExonGenomicCoordsMapper:
 
     async def _set_mane_genomic_data(
         self,
-        params: Dict,
+        params: dict,
         gene: str,
         alt_ac: str,
         pos: int,
         strand: Strand,
         is_start: bool,
-    ) -> Optional[str]:
+    ) -> str | None:
         """Set genomic data in `params` found from MANE.
 
         :param params: Parameters for response
@@ -596,9 +711,9 @@ class ExonGenomicCoordsMapper:
         :return: Warnings if found
         """
         start, end = get_inter_residue_pos(pos, pos, residue_mode=ResidueMode.ZERO)
-        mane_data: Optional[
-            CdnaRepresentation
-        ] = await self.mane_transcript.get_mane_transcript(
+        mane_data: (
+            CdnaRepresentation | None
+        ) = await self.mane_transcript.get_mane_transcript(
             alt_ac,
             start,
             end,
@@ -667,8 +782,8 @@ class ExonGenomicCoordsMapper:
         return None
 
     async def _set_genomic_data(
-        self, params: Dict, strand: Strand, is_start: bool
-    ) -> Optional[str]:
+        self, params: dict, strand: Strand, is_start: bool
+    ) -> str | None:
         """Set genomic data in ``params``
 
         :param params: Parameters for response
@@ -751,7 +866,7 @@ class ExonGenomicCoordsMapper:
 
     @staticmethod
     def _set_exon_offset(
-        params: Dict, start: int, end: int, pos: int, is_start: bool, strand: Strand
+        params: dict, start: int, end: int, pos: int, is_start: bool, strand: Strand
     ) -> None:
         """Set value for ``exon_offset`` in ``params``.
 
@@ -775,26 +890,23 @@ class ExonGenomicCoordsMapper:
                 params["exon_offset"] = pos - start
 
     async def _structure_exons(
-        self, transcript: str, alt_ac: Optional[str] = None
-    ) -> List[Tuple[int, int]]:
+        self, transcript: str, alt_ac: str | None = None
+    ) -> list[tuple[int, int]]:
         """Structure exons as list of tuples.
 
         :param transcript: Transcript accession
         :param alt_ac: Genomic accession
         :return: List of tuples containing transcript exon coordinates
         """
-        result = []
         tx_exons, _ = await self.uta_db.get_tx_exons(transcript, alt_ac=alt_ac)
 
         if not tx_exons:
-            return result
+            return []
 
-        for coords in tx_exons:
-            result.append((coords[0], coords[1]))
-        return result
+        return [(coords[0], coords[1]) for coords in tx_exons]
 
     @staticmethod
-    def _get_exon_number(tx_exons: List, tx_pos: int) -> int:
+    def _get_exon_number(tx_exons: list, tx_pos: int) -> int:
         """Find related exon number for a position
 
         :param tx_exons: List of exon coordinates for a transcript
@@ -807,3 +919,55 @@ class ExonGenomicCoordsMapper:
                 break
             i += 1
         return i
+
+    @staticmethod
+    def _get_adjacent_exon(
+        tx_exons_genomic_coords: list[tuple[int, int, int, int, int]],
+        strand: Strand,
+        start: int | None = None,
+        end: int | None = None,
+    ) -> int:
+        """Return the adjacent exon given a non-exonic breakpoint. For the positive
+        strand, adjacent is defined as the exon preceding the breakpoint for the 5' end
+        and the exon following the breakpoint for the 3' end. For the negative strand,
+        adjacent is defined as the exon following the breakpoint for the 5' end and the
+        exon preceding the breakpoint for the 3' end.
+
+        :param: tx_exons_genomic_coords: List of tuples describing exons and genomic
+            coordinates for a transcript. Each tuple contains the transcript number
+            (0-indexed), the transcript coordinates for the exon, and the genomic
+            coordinates for the exon. Pos 0 in the tuple corresponds to the exon
+            number, pos 1 and pos 2 refer to the start and end transcript coordinates,
+            respectively, and pos 3 and 4 refer to the start and end genomic
+            coordinates, respectively.
+        :param strand: Strand
+        :param: start: Genomic coordinate of breakpoint
+        :param: end: Genomic coordinate of breakpoint
+        :return: Exon number corresponding to adjacent exon. Will be 1-based
+        """
+        for i in range(len(tx_exons_genomic_coords) - 1):
+            exon = tx_exons_genomic_coords[i]
+            next_exon = tx_exons_genomic_coords[i + 1]
+            bp = start if start else end
+            if strand == strand.POSITIVE:
+                lte_exon = exon
+                gte_exon = next_exon
+            else:
+                lte_exon = next_exon
+                gte_exon = exon
+            if bp >= lte_exon[4] and bp <= gte_exon[3]:
+                break
+        # Return current exon if end position is provided, next exon if start position
+        # is provided. exon[0] needs to be incremented by 1 in both cases as exons are
+        # 0-based in UTA
+        return exon[0] + 1 if end else exon[0] + 2
+
+    @staticmethod
+    def _is_exonic_breakpoint(pos: int, tx_genomic_coords: list) -> bool:
+        """Check if a breakpoint occurs on an exon
+
+        :param pos: Genomic breakpoint
+        :param tx_genomic_coords: A list of genomic coordinates for a transcript
+        :return: True if the breakpoint occurs on an exon
+        """
+        return any(pos >= exon[3] and pos <= exon[4] for exon in tx_genomic_coords)