cool-seq-tool 0.3.0.dev1__py3-none-any.whl → 0.4.0.dev0__py3-none-any.whl

cool_seq_tool/api.py

@@ -24,16 +24,16 @@ def custom_openapi() -> Dict:
     if app.openapi_schema:
         return app.openapi_schema
     openapi_schema = get_openapi(
-        title="The GenomicMedLab Cool Seq Tool",
+        title="The GenomicMedLab Cool-Seq-Tool",
         version=__version__,
-        description="Common Operations On Lots-of Sequences Tool.",
+        description="Common Operations On Lots of Sequences Tool.",
         routes=app.routes,
     )
 
     openapi_schema["info"]["contact"] = {
         "name": "Alex H. Wagner",
         "email": "Alex.Wagner@nationwidechildrens.org",
-        "url": "https://www.nationwidechildrens.org/specialties/institute-for-genomic-medicine/research-labs/wagner-lab",  # noqa: E501
+        "url": "https://www.nationwidechildrens.org/specialties/institute-for-genomic-medicine/research-labs/wagner-lab",
     }
     app.openapi_schema = openapi_schema
     return app.openapi_schema

cool_seq_tool/app.py

@@ -1,4 +1,6 @@
-"""Module for initializing data sources."""
+"""Provides core CoolSeqTool class, which non-redundantly initializes all Cool-Seq-Tool
+data handler and mapping resources for straightforward access.
+"""
 import logging
 from pathlib import Path
 from typing import Optional
@@ -9,7 +11,7 @@ from cool_seq_tool.handlers.seqrepo_access import SeqRepoAccess
 from cool_seq_tool.mappers import (
     AlignmentMapper,
     ExonGenomicCoordsMapper,
-    MANETranscript,
+    ManeTranscript,
 )
 from cool_seq_tool.paths import (
     LRG_REFSEQGENE_PATH,
@@ -17,15 +19,34 @@ from cool_seq_tool.paths import (
     SEQREPO_ROOT_DIR,
     TRANSCRIPT_MAPPINGS_PATH,
 )
-from cool_seq_tool.sources.mane_transcript_mappings import MANETranscriptMappings
+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
+from cool_seq_tool.sources.uta_database import UTA_DB_URL, UtaDatabase
 
 logger = logging.getLogger(__name__)
 
 
 class CoolSeqTool:
-    """Class to initialize data sources."""
+    """Non-redundantly initialize all Cool-Seq-Tool data resources, available under the
+    following attribute names:
+
+    * ``self.seqrepo_access``: :py:class:`SeqRepoAccess <cool_seq_tool.handlers.seqrepo_access.SeqRepoAccess>`
+    * ``self.transcript_mappings``: :py:class:`TranscriptMappings <cool_seq_tool.sources.transcript_mappings.TranscriptMappings>`
+    * ``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.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>`
+
+    Initialization with default resource locations is straightforward:
+
+    .. code-block:: pycon
+
+       >>> from cool_seq_tool.app import CoolSeqTool
+       >>> cst = CoolSeqTool()
+
+    See the :ref:`configuration <configuration>` section for more information.
+    """
 
     def __init__(
         self,
@@ -37,11 +58,11 @@ class CoolSeqTool:
     ) -> None:
         """Initialize CoolSeqTool class
 
-        :param transcript_file_path: The path to transcript_mapping.tsv
-        :param lrg_refseqgene_path: The path to LRG_RefSeqGene
+        :param transcript_file_path: The path to ``transcript_mapping.tsv``
+        :param lrg_refseqgene_path: The path to the LRG_RefSeqGene file
         :param mane_data_path: Path to RefSeq MANE summary data
         :param db_url: PostgreSQL connection URL
-            Format: `driver://user:password@host/database/schema`
+            Format: ``driver://user:password@host/database/schema``
         :param sr: SeqRepo instance. If this is not provided, will create a new instance
         """
         if not sr:
@@ -51,14 +72,14 @@ class CoolSeqTool:
             transcript_file_path=transcript_file_path,
             lrg_refseqgene_path=lrg_refseqgene_path,
         )
-        self.mane_transcript_mappings = MANETranscriptMappings(
+        self.mane_transcript_mappings = ManeTranscriptMappings(
             mane_data_path=mane_data_path
         )
-        self.uta_db = UTADatabase(db_url=db_url)
+        self.uta_db = UtaDatabase(db_url=db_url)
         self.alignment_mapper = AlignmentMapper(
             self.seqrepo_access, self.transcript_mappings, self.uta_db
         )
-        self.mane_transcript = MANETranscript(
+        self.mane_transcript = ManeTranscript(
             self.seqrepo_access,
             self.transcript_mappings,
             self.mane_transcript_mappings,

cool_seq_tool/data/data_downloads.py

@@ -1,4 +1,4 @@
-"""Module for handling downloadable data files."""
+"""Handle acquisition of external data."""
 import datetime
 import gzip
 import logging
@@ -15,8 +15,11 @@ logger = logging.getLogger("cool_seq_tool")
 
 
 class DataDownload:
-    """Class for managing downloadable data files. Responsible for checking if files
-    are available under default locations, and fetching them if not.
+    """Manage downloadable data files. Responsible for checking if files are available
+    under expected locations, and fetching them if not.
+
+    Relevant methods are called automatically by data classes; users should not have
+    to interact with this class under normal circumstances.
     """
 
     def __init__(self) -> None:
@@ -25,7 +28,7 @@ class DataDownload:
 
     def get_mane_summary(self) -> Path:
         """Identify latest MANE summary data. If unavailable locally, download from
-        source.
+        `NCBI FTP server <https://ftp.ncbi.nlm.nih.gov/refseq/MANE/MANE_human/current/>`_.
 
         :return: path to MANE summary file
         """
@@ -52,7 +55,7 @@ class DataDownload:
 
     def get_lrg_refseq_gene_data(self) -> Path:
         """Identify latest LRG RefSeq Gene file. If unavailable locally, download from
-        source.
+        `NCBI FTP server <https://ftp.ncbi.nlm.nih.gov/refseq/H_sapiens/RefSeqGene/>`_.
 
         :return: path to acquired LRG RefSeq Gene data file
         """

cool_seq_tool/handlers/seqrepo_access.py

@@ -1,4 +1,6 @@
-"""A module for accessing SeqRepo."""
+"""Wrap SeqRepo to provide additional lookup and identification methods on top of basic
+dereferencing functions.
+"""
 import logging
 from os import environ
 from pathlib import Path
@@ -13,7 +15,9 @@ logger = logging.getLogger(__name__)
 
 
 class SeqRepoAccess(SeqRepoDataProxy):
-    """The SeqRepoAccess class."""
+    """Provide a wrapper around the base SeqRepoDataProxy class from ``VRS-Python`` to
+    provide additional lookup and identification methods.
+    """
 
     environ["SEQREPO_LRU_CACHE_MAXSIZE"] = "none"
 
@@ -24,25 +28,37 @@ class SeqRepoAccess(SeqRepoDataProxy):
         end: Optional[int] = None,
         residue_mode: ResidueMode = ResidueMode.RESIDUE,
     ) -> Tuple[str, Optional[str]]:
-        """Get reference sequence for an accession given a start and end position.
-        If `start` and `end` are not given, it will return the entire reference sequence
+        """Get reference sequence for an accession given a start and end position. If
+        ``start`` and ``end`` are not given, returns the entire reference sequence.
+
+        >>> from cool_seq_tool.handlers import SeqRepoAccess
+        >>> from biocommons.seqrepo import SeqRepo
+        >>> sr = SeqRepoAccess(SeqRepo("/usr/local/share/seqrepo/latest"))
+        >>> sr.get_reference_sequence("NM_002529.3", 1, 10)[0]
+        'TGCAGCTGG'
+        >>> sr.get_reference_sequence("NP_001341538.1", 1, 10)[0]
+        'MAALSGGGG'
 
         :param ac: Accession
         :param start: Start pos change
-        :param end: End pos change. If `None` assumes both `start` and `end` have same
-            values, if `start` exists.
-        :param residue_mode: Residue mode for `start` and `end`
+        :param end: End pos change. If ``None`` assumes both ``start`` and ``end`` have
+            same values, if ``start`` exists.
+        :param residue_mode: Residue mode for ``start`` and ``end``
         :return: Sequence at position (if accession and positions actually
             exist, else return empty string), warning if any
         """
-        if start or end:
-            pos, warning = get_inter_residue_pos(start, residue_mode, end_pos=end)
-            if pos is None:
-                return "", warning
-            else:
-                start, end = pos
-                if start == end:
-                    end += 1
+        if start and end:
+            if start > end:
+                msg = f"start ({start}) cannot be greater than end ({end})"
+                return "", msg
+
+            start, end = get_inter_residue_pos(start, end, residue_mode)
+            if start == end:
+                end += 1
+        else:
+            if start is not None and residue_mode == ResidueMode.RESIDUE:
+                start -= 1
+
         try:
             sequence = self.sr.fetch(ac, start=start, end=end)
         except KeyError:
@@ -53,18 +69,12 @@ class SeqRepoAccess(SeqRepoDataProxy):
             error = str(e)
             if error.startswith("start out of range"):
                 msg = (
-                    f"Start inter-residue coordinate ({start}) is out of "
-                    f"index on {ac}"
+                    f"Start inter-residue coordinate ({start}) is out of index on {ac}"
                 )
             elif error.startswith("stop out of range"):
                 msg = (
                     f"End inter-residue coordinate ({end}) is out of " f"index on {ac}"
                 )
-            elif error.startswith("invalid coordinates") and ">" in error:
-                msg = (
-                    f"Invalid inter-residue coordinates: start ({start}) "
-                    f"cannot be greater than end ({end})"
-                )
             else:
                 msg = f"{e}"
             logger.warning(msg)
@@ -78,8 +88,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
                 if len(sequence) != expected_len_of_seq:
                     return (
                         "",
-                        f"End inter-residue coordinate ({end})"
-                        f" is out of index on {ac}",
+                        f"End inter-residue coordinate ({end}) is out of index on {ac}",
                     )
             return sequence, None
 
@@ -88,6 +97,14 @@ class SeqRepoAccess(SeqRepoDataProxy):
     ) -> Tuple[List[str], Optional[str]]:
         """Return list of identifiers for accession.
 
+        >>> from cool_seq_tool.handlers import SeqRepoAccess
+        >>> from biocommons.seqrepo import SeqRepo
+        >>> sr = SeqRepoAccess(SeqRepo("/usr/local/share/seqrepo/latest"))
+        >>> sr.translate_identifier("NM_002529.3")[0]
+        ['MD5:18f0a6e3af9e1bbd8fef1948c7156012', 'NCBI:NM_002529.3', 'refseq:NM_002529.3', 'SEGUID:dEJQBkga9d9VeBHTyTbg6JEtTGQ', 'SHA1:74425006481af5df557811d3c936e0e8912d4c64', 'VMC:GS_RSkww1aYmsMiWbNdNnOTnVDAM3ZWp1uA', 'sha512t24u:RSkww1aYmsMiWbNdNnOTnVDAM3ZWp1uA', 'ga4gh:SQ.RSkww1aYmsMiWbNdNnOTnVDAM3ZWp1uA']
+        >>> sr.translate_identifier("NM_002529.3", "ga4gh")[0]
+        ['ga4gh:SQ.RSkww1aYmsMiWbNdNnOTnVDAM3ZWp1uA']
+
         :param ac: Identifier accession
         :param target_namespace: The namespace(s) of identifier to return
         :return: List of identifiers, warning
@@ -123,7 +140,7 @@ class SeqRepoAccess(SeqRepoDataProxy):
     ) -> Tuple[Optional[List[str]], Optional[str]]:
         """Get accessions for a chromosome
 
-        :param str chromosome: Chromosome number. Must be either 1-22, X, or Y
+        :param chromosome: Chromosome number. Must be either 1-22, X, or Y
         :return: Accessions for chromosome (ordered by latest assembly)
         """
         acs = []
@@ -160,9 +177,20 @@ class SeqRepoAccess(SeqRepoDataProxy):
 
     def get_fasta_file(self, sequence_id: str, outfile_path: Path) -> None:
         """Retrieve FASTA file containing sequence for requested sequence ID.
-        :param sequence_id: accession ID, sans namespace, eg `NM_152263.3`
+
+        >>> from pathlib import Path
+        >>> from cool_seq_tool.handlers import SeqRepoAccess
+        >>> from biocommons.seqrepo import SeqRepo
+        >>> sr = SeqRepoAccess(SeqRepo("/usr/local/share/seqrepo/latest"))
+        >>> # write to local file tpm3.fasta:
+        >>> sr.get_fasta_file("NM_002529.3", Path("tpm3.fasta"))
+
+        FASTA file headers will include GA4GH sequence digest, Ensembl accession ID,
+        and RefSeq accession ID.
+
+        :param sequence_id: accession ID, sans namespace, eg ``NM_152263.3``
         :param outfile_path: path to save file to
-        :return: None, but saves sequence data to `outfile_path` if successful
+        :return: None, but saves sequence data to ``outfile_path`` if successful
         :raise: KeyError if SeqRepo doesn't have sequence data for the given ID
         """
         sequence = self.get_reference_sequence(sequence_id)[0]

cool_seq_tool/mappers/__init__.py

@@ -1,4 +1,7 @@
 """Module for mapping data"""
 from .alignment import AlignmentMapper  # noqa: I001
-from .mane_transcript import MANETranscript
+from .mane_transcript import ManeTranscript
 from .exon_genomic_coords import ExonGenomicCoordsMapper
+
+
+__all__ = ["AlignmentMapper", "ManeTranscript", "ExonGenomicCoordsMapper"]

cool_seq_tool/mappers/alignment.py

@@ -5,7 +5,7 @@ from typing import Dict, Optional, Tuple
 
 from cool_seq_tool.handlers.seqrepo_access import SeqRepoAccess
 from cool_seq_tool.schemas import AnnotationLayer, Assembly, ResidueMode
-from cool_seq_tool.sources import TranscriptMappings, UTADatabase
+from cool_seq_tool.sources import TranscriptMappings, UtaDatabase
 
 
 class AlignmentMapper:
@@ -15,15 +15,14 @@ class AlignmentMapper:
         self,
         seqrepo_access: SeqRepoAccess,
         transcript_mappings: TranscriptMappings,
-        uta_db: UTADatabase,
+        uta_db: UtaDatabase,
     ) -> None:
         """Initialize the AlignmentMapper class.
 
-        :param SeqRepoAccess seqrepo_access: Access to seqrepo queries
-        :param TranscriptMappings transcript_mappings: Access to transcript
-            accession mappings and conversions
-        :param UTADatabase uta_db: UTADatabase instance to give access to query
-            UTA database
+        :param seqrepo_access: Access to seqrepo queries
+        :param transcript_mappings: Access to transcript accession mappings and
+            conversions
+        :param uta_db: UtaDatabase instance to give access to query UTA database
         """
         self.seqrepo_access = seqrepo_access
         self.transcript_mappings = transcript_mappings
@@ -38,15 +37,16 @@ class AlignmentMapper:
     ) -> Tuple[Optional[Dict], Optional[str]]:
         """Translate protein representation to cDNA representation.
 
-        :param str p_ac: Protein RefSeq accession
-        :param int p_start_pos: Protein start position
-        :param int p_end_pos: Protein end position
-        :param ResidueMode residue_mode: Residue mode for `p_start_pos` and `p_end_pos`
+        :param p_ac: Protein RefSeq accession
+        :param p_start_pos: Protein start position
+        :param p_end_pos: Protein end position
+        :param residue_mode: Residue mode for ``p_start_pos`` and ``p_end_pos``
         :return: Tuple containing:
-            - cDNA representation (accession, codon range positions for corresponding
-              change, cds start site) if able to translate. Will return positions as
-              inter-residue coordinates. If unable to translate, returns `None`.
-            - Warning, if unable to translate to cDNA representation. Else `None`
+
+        * cDNA representation (accession, codon range positions for corresponding
+          change, cds start site) if able to translate. Will return positions as
+          inter-residue coordinates. If unable to translate, returns ``None``.
+        * Warning, if unable to translate to cDNA representation. Else ``None``
         """
         # Get cDNA accession
         temp_c_ac = await self.uta_db.p_to_c_ac(p_ac)
@@ -86,10 +86,10 @@ class AlignmentMapper:
     async def _get_cds_start(self, c_ac: str) -> Tuple[Optional[int], Optional[str]]:
         """Get CDS start for a given cDNA RefSeq accession
 
-        :param str c_ac: cDNA RefSeq accession
+        :param c_ac: cDNA RefSeq accession
         :return: Tuple containing:
-            - CDS start site if found. Else `None`
-            - Warning, if unable to get CDS start. Else `None`
+            - CDS start site if found. Else ``None``
+            - Warning, if unable to get CDS start. Else ``None``
         """
         cds_start_end = await self.uta_db.get_cds_start_end(c_ac)
         if not cds_start_end:
@@ -111,16 +111,17 @@ class AlignmentMapper:
     ) -> Tuple[Optional[Dict], Optional[str]]:
         """Translate cDNA representation to genomic representation
 
-        :param str c_ac: cDNA RefSeq accession
-        :param int c_start_pos: cDNA start position for codon
-        :param int c_end_pos: cDNA end position for codon
-        :param Optional[int] coding_start_site: Coding start site. If not provided,
-            this will be computed.
-        :param Assembly target_genome_assembly: Genome assembly to get genomic data for
+        :param c_ac: cDNA RefSeq accession
+        :param c_start_pos: cDNA start position for codon
+        :param c_end_pos: cDNA end position for codon
+        :param coding_start_site: Coding start site. If not provided, this will be
+            computed.
+        :param target_genome_assembly: Genome assembly to get genomic data for
         :return: Tuple containing:
-            - Genomic representation (ac, positions) if able to translate. Will return
-              positions as inter-residue coordinates. Else `None`.
-            - Warning, if unable to translate to genomic representation. Else `None`
+
+        * Genomic representation (ac, positions) if able to translate. Will return
+          positions as inter-residue coordinates. Else ``None``.
+        * Warning, if unable to translate to genomic representation. Else ``None``
         """
         if any(
             (
@@ -212,17 +213,19 @@ class AlignmentMapper:
         residue_mode: ResidueMode = ResidueMode.INTER_RESIDUE,
         target_genome_assembly: Assembly = Assembly.GRCH38,
     ) -> Tuple[Optional[Dict], Optional[str]]:
-        """Translate protein representation to genomic representation
-
-        :param str p_ac: Protein RefSeq accession
-        :param int p_start_pos: Protein start position
-        :param int p_end_pos: Protein end position
-        :param ResidueMode residue_mode: Residue mode for `p_start_pos` and `p_end_pos`.
-        :param Assembly target_genome_assembly: Genome assembly to get genomic data for
+        """Translate protein representation to genomic representation, by way of
+        intermediary conversion into cDNA coordinates.
+
+        :param p_ac: Protein RefSeq accession
+        :param p_start_pos: Protein start position
+        :param p_end_pos: Protein end position
+        :param residue_mode: Residue mode for ``p_start_pos`` and ``p_end_pos``.
+        :param target_genome_assembly: Genome assembly to get genomic data for
         :return: Tuple containing:
-            - Genomic representation (ac, positions) if able to translate. Will return
-              positions as inter-residue coordinates. Else `None`.
-            and warnings. The genomic data will always return inter-residue coordinates
+
+        * Genomic representation (ac, positions) if able to translate. Will return
+          positions as inter-residue coordinates. Else ``None``.
+        * Warnings, if conversion to cDNA or genomic coordinates fails.
         """
         c_data, warning = await self.p_to_c(
             p_ac, p_start_pos, p_end_pos, residue_mode=residue_mode