cool-seq-tool 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

cool_seq_tool/__init__.py

@@ -1,12 +1,10 @@
 """The cool_seq_tool package"""
 
-import logging
+from importlib.metadata import PackageNotFoundError, version
 
-logging.basicConfig(
-    filename="cool_seq_tool.log",
-    format="[%(asctime)s] - %(name)s - %(levelname)s : %(message)s",
-)
-logger = logging.getLogger("cool_seq_tool")
-logger.setLevel(logging.DEBUG)
-
-LOG_FN = "cool_seq_tool.log"
+try:
+    __version__ = version("cool_seq_tool")
+except PackageNotFoundError:
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError

cool_seq_tool/app.py

@@ -11,13 +11,14 @@ from cool_seq_tool.handlers.seqrepo_access import SEQREPO_ROOT_DIR, SeqRepoAcces
 from cool_seq_tool.mappers import (
     AlignmentMapper,
     ExonGenomicCoordsMapper,
+    LiftOver,
     ManeTranscript,
 )
 from cool_seq_tool.sources.mane_transcript_mappings import ManeTranscriptMappings
 from cool_seq_tool.sources.transcript_mappings import TranscriptMappings
 from cool_seq_tool.sources.uta_database import UTA_DB_URL, UtaDatabase
 
-logger = logging.getLogger(__name__)
+_logger = logging.getLogger(__name__)
 
 
 class CoolSeqTool:
@@ -29,6 +30,7 @@ class CoolSeqTool:
     * ``self.mane_transcript_mappings``: :py:class:`ManeTranscriptMappings <cool_seq_tool.sources.mane_transcript_mappings.ManeTranscriptMappings>`
     * ``self.uta_db``: :py:class:`UtaDatabase <cool_seq_tool.sources.uta_database.UtaDatabase>`
     * ``self.alignment_mapper``: :py:class:`AlignmentMapper <cool_seq_tool.mappers.alignment.AlignmentMapper>`
+    * ``self.liftover``: :py:class:`LiftOver <cool_seq_tool.mappers.liftover.LiftOver>`
     * ``self.mane_transcript``: :py:class:`ManeTranscript <cool_seq_tool.mappers.mane_transcript.ManeTranscript>`
     * ``self.ex_g_coords_mapper``: :py:class:`ExonGenomicCoordsMapper <cool_seq_tool.mappers.exon_genomic_coords.ExonGenomicCoordsMapper>`
     """
@@ -94,15 +96,18 @@ class CoolSeqTool:
         self.alignment_mapper = AlignmentMapper(
             self.seqrepo_access, self.transcript_mappings, self.uta_db
         )
+        self.liftover = LiftOver()
         self.mane_transcript = ManeTranscript(
             self.seqrepo_access,
             self.transcript_mappings,
             self.mane_transcript_mappings,
             self.uta_db,
+            self.liftover,
         )
         self.ex_g_coords_mapper = ExonGenomicCoordsMapper(
             self.seqrepo_access,
             self.uta_db,
             self.mane_transcript,
             self.mane_transcript_mappings,
+            self.liftover,
         )

cool_seq_tool/handlers/seqrepo_access.py

@@ -8,10 +8,10 @@ from pathlib import Path
 
 from ga4gh.vrs.dataproxy import SeqRepoDataProxy
 
-from cool_seq_tool.schemas import ResidueMode
-from cool_seq_tool.utils import get_inter_residue_pos
+from cool_seq_tool.schemas import Assembly, ResidueMode
+from cool_seq_tool.utils import get_inter_residue_pos, process_chromosome_input
 
-logger = logging.getLogger(__name__)
+_logger = logging.getLogger(__name__)
 
 
 SEQREPO_ROOT_DIR = environ.get("SEQREPO_ROOT_DIR", "/usr/local/share/seqrepo/latest")
@@ -66,7 +66,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
             sequence = self.sr.fetch(ac, start=start, end=end)
         except KeyError:
             msg = f"Accession, {ac}, not found in SeqRepo"
-            logger.warning(msg)
+            _logger.warning(msg)
             return "", msg
         except ValueError as e:
             error = str(e)
@@ -80,7 +80,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
                 )
             else:
                 msg = f"{e}"
-            logger.warning(msg)
+            _logger.warning(msg)
             return "", msg
         else:
             # If start is valid, but end is invalid, SeqRepo still returns
@@ -118,7 +118,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
             )
         except KeyError:
             msg = f"SeqRepo unable to get translated identifiers for {ac}"
-            logger.warning(msg)
+            _logger.warning(msg)
             return [], msg
         else:
             return ga4gh_identifiers, None
@@ -133,7 +133,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
             return self.sr.translate_alias(input_str), None
         except KeyError:
             msg = f"SeqRepo could not translate alias {input_str}"
-            logger.warning(msg)
+            _logger.warning(msg)
             return [], msg
 
     def chromosome_to_acs(self, chromosome: str) -> tuple[list[str] | None, str | None]:
@@ -143,14 +143,18 @@ class SeqRepoAccess(SeqRepoDataProxy):
         :return: Accessions for chromosome (ordered by latest assembly)
         """
         acs = []
-        for assembly in ["GRCh38", "GRCh37"]:
+        for assembly in reversed(Assembly.values()):
             tmp_acs, _ = self.translate_identifier(
-                f"{assembly}:chr{chromosome}", target_namespaces="refseq"
+                f"{assembly}:{process_chromosome_input(chromosome)}",
+                target_namespaces="refseq",
             )
             acs += [ac.split("refseq:")[-1] for ac in tmp_acs]
         if acs:
             return acs, None
-        return None, f"{chromosome} is not a valid chromosome"
+        return (
+            None,
+            f'Unable to find matching accessions for "{chromosome}" in SeqRepo.',
+        )
 
     def ac_to_chromosome(self, ac: str) -> tuple[str | None, str | None]:
         """Get chromosome for accession.

cool_seq_tool/mappers/__init__.py

@@ -1,8 +1,9 @@
 """Module for mapping data"""
 
 from .alignment import AlignmentMapper  # noqa: I001
+from .liftover import LiftOver
 from .mane_transcript import ManeTranscript
 from .exon_genomic_coords import ExonGenomicCoordsMapper
 
 
-__all__ = ["AlignmentMapper", "ManeTranscript", "ExonGenomicCoordsMapper"]
+__all__ = ["AlignmentMapper", "LiftOver", "ManeTranscript", "ExonGenomicCoordsMapper"]

cool_seq_tool/mappers/exon_genomic_coords.py

@@ -4,6 +4,7 @@ import logging
 from typing import Literal, TypeVar
 
 from cool_seq_tool.handlers.seqrepo_access import SeqRepoAccess
+from cool_seq_tool.mappers.liftover import LiftOver
 from cool_seq_tool.mappers.mane_transcript import CdnaRepresentation, ManeTranscript
 from cool_seq_tool.schemas import (
     AnnotationLayer,
@@ -23,7 +24,7 @@ CoordinatesResponseType = TypeVar(
     "CoordinatesResponseType", GenomicDataResponse, TranscriptExonDataResponse
 )
 
-logger = logging.getLogger(__name__)
+_logger = logging.getLogger(__name__)
 
 
 class ExonGenomicCoordsMapper:
@@ -37,6 +38,7 @@ class ExonGenomicCoordsMapper:
         uta_db: UtaDatabase,
         mane_transcript: ManeTranscript,
         mane_transcript_mappings: ManeTranscriptMappings,
+        liftover: LiftOver,
     ) -> None:
         """Initialize ExonGenomicCoordsMapper class.
 
@@ -63,25 +65,28 @@ class ExonGenomicCoordsMapper:
         :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
+        :param liftover: Instance to provide mapping between human genome assemblies
         """
         self.seqrepo_access = seqrepo_access
         self.uta_db = uta_db
         self.mane_transcript = mane_transcript
         self.mane_transcript_mappings = mane_transcript_mappings
+        self.liftover = liftover
 
     @staticmethod
     def _return_warnings(
-        resp: CoordinatesResponseType, warning_msg: str
+        resp: CoordinatesResponseType, warning_msg: list[str]
     ) -> CoordinatesResponseType:
         """Add warnings to response object
 
         :param resp: Response object
-        :param warning_msg: Warning message on why ``transcript_exon_data`` or
+        :param warning_msg: Warning message(s) on why ``transcript_exon_data`` or
             ``genomic_data`` field is ``None``
         :return: Response object with warning message
         """
-        logger.warning(warning_msg)
-        resp.warnings.append(warning_msg)
+        for msg in warning_msg:
+            _logger.warning(msg)
+            resp.warnings.append(msg)
         return resp
 
     async def transcript_to_genomic_coordinates(
@@ -126,42 +131,44 @@ class ExonGenomicCoordsMapper:
         )
 
         # Ensure valid inputs
+        warnings = []
         if not transcript:
-            return self._return_warnings(resp, "Must provide `transcript`")
-        transcript = transcript.strip()
+            warnings.append("Must provide `transcript`")
+        else:
+            transcript = transcript.strip()
 
         exon_start_exists, exon_end_exists = False, False
         if exon_start is not None:
             if exon_start < 1:
-                return self._return_warnings(resp, "`exon_start` cannot be less than 1")
+                warnings.append("`exon_start` cannot be less than 1")
             exon_start_exists = True
 
         if exon_end is not None:
             if exon_end < 1:
-                return self._return_warnings(resp, "`exon_end` cannot be less than 1")
+                warnings.append("`exon_end` cannot be less than 1")
             exon_end_exists = True
 
         if not exon_start_exists and not exon_end_exists:
-            return self._return_warnings(
-                resp, "Must provide either `exon_start` or `exon_end`"
-            )
+            warnings.append("Must provide either `exon_start` or `exon_end`")
         if exon_start_exists and exon_end_exists and (exon_start > exon_end):
-            return self._return_warnings(
-                resp,
-                f"Start exon {exon_start} is greater than end exon {exon_end}",
+            warnings.append(
+                f"Start exon {exon_start} is greater than end exon {exon_end}"
             )
 
+        if warnings:
+            return self._return_warnings(resp, warnings)
+
         # Get all exons and associated start/end coordinates for transcript
         tx_exons, warning = await self.uta_db.get_tx_exons(transcript)
         if not tx_exons:
-            return self._return_warnings(resp, warning or "")
+            return self._return_warnings(resp, [warning] if warning else [])
 
         # Get exon start and exon end coordinates
         tx_exon_coords, warning = self.get_tx_exon_coords(
             transcript, tx_exons, exon_start, exon_end
         )
         if not tx_exon_coords:
-            return self._return_warnings(resp, warning or "")
+            return self._return_warnings(resp, [warning] if warning else [])
         tx_exon_start_coords, tx_exon_end_coords = tx_exon_coords
 
         if gene:
@@ -173,7 +180,7 @@ class ExonGenomicCoordsMapper:
             transcript, tx_exon_start_coords, tx_exon_end_coords, gene=gene
         )
         if not alt_ac_start_end:
-            return self._return_warnings(resp, warning or "")
+            return self._return_warnings(resp, [warning] if warning else [])
         alt_ac_start_data, alt_ac_end_data = alt_ac_start_end
 
         # Get gene and chromosome data, check that at least one was retrieved
@@ -182,8 +189,9 @@ class ExonGenomicCoordsMapper:
         if gene is None or chromosome is None:
             return self._return_warnings(
                 resp,
-                "Unable to retrieve `gene` or `chromosome` from genomic start and "
-                "genomic end data",
+                [
+                    "Unable to retrieve `gene` or `chromosome` from genomic start and genomic end data"
+                ],
             )
 
         g_start = alt_ac_start_data[3] - 1 if alt_ac_start_data else None
@@ -259,9 +267,8 @@ class ExonGenomicCoordsMapper:
         >>> result.genomic_data.exon_start, result.genomic_data.exon_end
         (1, 8)
 
-        :param chromosome: Chromosome. Must give chromosome without a prefix
-            (i.e. ``1`` or ``X``). If not provided, must provide ``alt_ac``.
-            If ``alt_ac`` is also provided, ``alt_ac`` will be used.
+        :param chromosome: e.g. ``"1"`` or ``"chr1"``. If not provided, must provide
+            ``alt_ac``. If ``alt_ac`` is also provided, ``alt_ac`` will be used.
         :param alt_ac: Genomic accession (i.e. ``NC_000001.11``). If not provided,
             must provide ``chromosome. If ``chromosome`` is also provided, ``alt_ac``
             will be used.
@@ -279,14 +286,23 @@ class ExonGenomicCoordsMapper:
             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 gene: gene name. Ideally, HGNC symbol. Must be given if no ``transcript``
+            value is provided.
         :param residue_mode: Residue mode for ``start`` and ``end``
         :return: Genomic data (inter-residue coordinates)
         """
         resp = GenomicDataResponse(
             genomic_data=None, warnings=[], service_meta=service_meta()
         )
+        warnings = []
         if start is None and end is None:
-            return self._return_warnings(resp, "Must provide either `start` or `end`")
+            warnings.append("Must provide either `start` or `end`")
+        if chromosome is None and alt_ac is None:
+            warnings.append("Must provide either `chromosome` or `alt_ac`")
+        if transcript is None and gene is None:
+            warnings.append("Must provide either `gene` or `transcript`")
+        if warnings:
+            return self._return_warnings(resp, warnings)
 
         params = {key: None for key in GenomicData.model_fields}
         if gene is not None:
@@ -310,7 +326,7 @@ class ExonGenomicCoordsMapper:
             if start_data.transcript_exon_data:
                 start_data = start_data.transcript_exon_data.model_dump()
             else:
-                return self._return_warnings(resp, start_data.warnings[0])
+                return self._return_warnings(resp, [start_data.warnings[0]])
         else:
             start_data = None
 
@@ -330,7 +346,7 @@ class ExonGenomicCoordsMapper:
             if end_data.transcript_exon_data:
                 end_data = end_data.transcript_exon_data.model_dump()
             else:
-                return self._return_warnings(resp, end_data.warnings[0])
+                return self._return_warnings(resp, [end_data.warnings[0]])
         else:
             end_data = None
 
@@ -341,7 +357,7 @@ class ExonGenomicCoordsMapper:
                         f"Start `{field}`, {start_data[field]}, does "
                         f"not match End `{field}`, {end_data[field]}"
                     )
-                    return self._return_warnings(resp, msg)
+                    return self._return_warnings(resp, [msg])
                 params[field] = start_data[field]
             else:
                 params[field] = end_data[field]
@@ -351,7 +367,7 @@ class ExonGenomicCoordsMapper:
                 f"Input gene, {gene}, does not match expected output"
                 f"gene, {params['gene']}"
             )
-            return self._return_warnings(resp, msg)
+            return self._return_warnings(resp, [msg])
 
         for label, data in [("start", start_data), ("end", end_data)]:
             if data:
@@ -436,7 +452,7 @@ class ExonGenomicCoordsMapper:
         """
         if tx_exon_start is None and tx_exon_end is None:
             msg = "Must provide either `tx_exon_start` or `tx_exon_end` or both"
-            logger.warning(msg)
+            _logger.warning(msg)
             return None, msg
 
         alt_ac_data = {"start": None, "end": None}
@@ -462,7 +478,7 @@ class ExonGenomicCoordsMapper:
                         error = "Genomic accession does not match"
                     else:
                         error = "Strand does not match"
-                    logger.warning(
+                    _logger.warning(
                         "%s: %s != %s",
                         error,
                         alt_ac_data["start"][i],
@@ -510,25 +526,22 @@ class ExonGenomicCoordsMapper:
         resp = TranscriptExonDataResponse(
             transcript_exon_data=None, warnings=[], service_meta=service_meta()
         )
-
-        if transcript is None and gene is None:
-            return self._return_warnings(
-                resp, "Must provide either `gene` or `transcript`"
-            )
-
         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",
+                    [
+                        "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_ac:
+                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 alt_acs:
+                    return self._return_warnings(resp, [w])
+                alt_ac = alt_acs[0]
 
             if not transcript:
                 # Select a transcript if not provided
@@ -562,14 +575,14 @@ class ExonGenomicCoordsMapper:
                         else:
                             return self._return_warnings(
                                 resp,
-                                f"Could not find a transcript for {gene} on {alt_ac}",
+                                [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)
+                return self._return_warnings(resp, [w])
 
             # Check if breakpoint occurs on an exon.
             # If not, determine the adjacent exon given the selected transcript
@@ -603,7 +616,7 @@ class ExonGenomicCoordsMapper:
             # Check if valid accession is given
             if not await self.uta_db.validate_genomic_ac(alt_ac):
                 return self._return_warnings(
-                    resp, f"Invalid genomic accession: {alt_ac}"
+                    resp, [f"Invalid genomic accession: {alt_ac}"]
                 )
 
             genes_alt_acs, warning = await self.uta_db.get_genes_and_alt_acs(
@@ -626,11 +639,11 @@ class ExonGenomicCoordsMapper:
             genes_alt_acs = None
 
         if not genes_alt_acs:
-            return self._return_warnings(resp, warning)
+            return self._return_warnings(resp, [warning])
 
         gene_alt_ac, warning = self._get_gene_and_alt_ac(genes_alt_acs, gene)
         if not gene_alt_ac:
-            return self._return_warnings(resp, warning)
+            return self._return_warnings(resp, [warning])
         gene, alt_ac = gene_alt_ac
 
         if transcript is None:
@@ -638,7 +651,7 @@ class ExonGenomicCoordsMapper:
                 params, gene, alt_ac, pos, strand, is_start
             )
             if warnings:
-                return self._return_warnings(resp, warnings)
+                return self._return_warnings(resp, [warnings])
         else:
             params["transcript"] = transcript
             params["gene"] = gene
@@ -646,7 +659,7 @@ class ExonGenomicCoordsMapper:
             params["chr"] = alt_ac
             warning = await self._set_genomic_data(params, strand, is_start)
             if warning:
-                return self._return_warnings(resp, warning)
+                return self._return_warnings(resp, [warning])
 
         resp.transcript_exon_data = TranscriptExonData(**params)
         return resp
@@ -726,7 +739,7 @@ class ExonGenomicCoordsMapper:
             msg = f"Unable to find mane data for {alt_ac} with position {pos}"
             if gene:
                 msg += f" on gene {gene}"
-            logger.warning(msg)
+            _logger.warning(msg)
             return msg
 
         params["gene"] = mane_data.gene
@@ -750,7 +763,7 @@ class ExonGenomicCoordsMapper:
                 f"{params['transcript']} with position {tx_pos} "
                 f"does not exist on exons: {tx_exons}"
             )
-            logger.warning(msg)
+            _logger.warning(msg)
             return msg
 
         strand_to_use = strand if strand is not None else mane_data.strand
@@ -805,7 +818,7 @@ class ExonGenomicCoordsMapper:
                 return f"Unable to get chromosome and assembly for " f"{params['chr']}"
 
             chromosome_number, assembly = descr
-            liftover_data = self.uta_db.get_liftover(
+            liftover_data = self.liftover.get_liftover(
                 chromosome_number, params["pos"], Assembly.GRCH38
             )
             if liftover_data is None:

cool_seq_tool/mappers/liftover.py

@@ -0,0 +1,90 @@
+"""Module for mapping to/from human genome assemblies.
+
+Currently only supports GRCh37 <-> GRCh38
+"""
+
+import logging
+from os import environ
+
+from agct import Converter, Genome
+
+from cool_seq_tool.schemas import Assembly
+from cool_seq_tool.utils import process_chromosome_input
+
+# Environment variables for paths to chain files for agct
+LIFTOVER_CHAIN_37_TO_38 = environ.get("LIFTOVER_CHAIN_37_TO_38")
+LIFTOVER_CHAIN_38_TO_37 = environ.get("LIFTOVER_CHAIN_38_TO_37")
+
+
+_logger = logging.getLogger(__name__)
+
+
+class LiftOver:
+    """Class for mapping to/from human genome assemblies
+
+    Currently only supports GRCh37 <-> GRCh38
+    """
+
+    def __init__(
+        self,
+        chain_file_37_to_38: str | None = None,
+        chain_file_38_to_37: str | None = None,
+    ) -> None:
+        """Initialize liftover class
+
+        :param chain_file_37_to_38: Optional path to chain file for 37 to 38 assembly.
+            This is used for ``agct``. If this is not provided, will check to see
+            if ``LIFTOVER_CHAIN_37_TO_38`` env var is set. If neither is provided, will
+            allow ``agct`` to download a chain file from UCSC
+        :param chain_file_38_to_37: Optional path to chain file for 38 to 37 assembly.
+            This is used for ``agct``. If this is not provided, will check to see
+            if ``LIFTOVER_CHAIN_38_TO_37`` env var is set. If neither is provided, will
+            allow ``agct`` to download a chain file from UCSC
+        """
+        self.from_37_to_38 = Converter(
+            chainfile=chain_file_37_to_38 or LIFTOVER_CHAIN_37_TO_38,
+            from_db=Genome.HG19,
+            to_db=Genome.HG38,
+        )
+        self.from_38_to_37 = Converter(
+            chainfile=chain_file_38_to_37 or LIFTOVER_CHAIN_38_TO_37,
+            from_db=Genome.HG38,
+            to_db=Genome.HG19,
+        )
+
+    def get_liftover(
+        self, chromosome: str, pos: int, liftover_to_assembly: Assembly
+    ) -> tuple[str, int] | None:
+        """Get new genome assembly data for a position on a chromosome.
+
+        Use a UCSC-style chromosome name:
+
+        >>> from cool_seq_tool.mappers import LiftOver
+        >>> from cool_seq_tool.schemas import Assembly
+        >>> lo = LiftOver()
+        >>> lo.get_liftover("chr7", 140453136, Assembly.GRCH38)
+        ('chr7', 140753336)
+
+        Chromosome names can also be NCBI-style, without prefixes:
+
+        >>> lo.get_liftover("7", 140453136, Assembly.GRCH38)
+        ('chr7', 140753336)
+
+        :param chromosome: The chromosome number, e.g. ``"chr7"``, ``"chrX"``, ``"5"``.
+        :param pos: Position on the chromosome
+        :param liftover_to_assembly: Assembly to liftover to
+        :return: Target chromosome and target position for assembly
+        """
+        chromosome = process_chromosome_input(chromosome, "LiftOver.get_liftover()")
+        if liftover_to_assembly == Assembly.GRCH38:
+            liftover = self.from_37_to_38.convert_coordinate(chromosome, pos)
+        elif liftover_to_assembly == Assembly.GRCH37:
+            liftover = self.from_38_to_37.convert_coordinate(chromosome, pos)
+        else:
+            _logger.warning("%s assembly not supported", liftover_to_assembly)
+            liftover = None
+
+        if not liftover:
+            _logger.warning("%s does not exist on %s", pos, chromosome)
+            return None
+        return liftover[0][:2]