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

cool_seq_tool/sources/uta_database.py

@@ -1,4 +1,4 @@
-"""Module for UTA queries."""
+"""Provide transcript lookup and metadata tools via the UTA database."""
 import ast
 import base64
 import logging
@@ -14,24 +14,34 @@ from asyncpg.exceptions import InterfaceError, InvalidAuthorizationSpecification
 from botocore.exceptions import ClientError
 from pyliftover import LiftOver
 
-from cool_seq_tool.schemas import AnnotationLayer, Assembly
+from cool_seq_tool.schemas import AnnotationLayer, Assembly, Strand
 
-# use `bound` to upper-bound UTADatabase or child classes
-UTADatabaseType = TypeVar("UTADatabaseType", bound="UTADatabase")
+# use `bound` to upper-bound UtaDatabase or child classes
+UTADatabaseType = TypeVar("UTADatabaseType", bound="UtaDatabase")
 
 # Environment variables for paths to chain files for pyliftover
 LIFTOVER_CHAIN_37_TO_38 = environ.get("LIFTOVER_CHAIN_37_TO_38")
 LIFTOVER_CHAIN_38_TO_37 = environ.get("LIFTOVER_CHAIN_38_TO_37")
 
 UTA_DB_URL = environ.get(
-    "UTA_DB_URL", "postgresql://uta_admin:uta@localhost:5433/uta/uta_20210129"
+    "UTA_DB_URL", "postgresql://uta_admin:uta@localhost:5433/uta/uta_20210129b"
 )
 
 logger = logging.getLogger(__name__)
 
 
-class UTADatabase:
-    """Class for connecting and querying UTA database."""
+class UtaDatabase:
+    """Provide transcript lookup and metadata tools via the Universal Transcript Archive
+    (UTA) database.
+
+    Users should use the ``create()`` method to construct a new instance. Note that
+    almost all public methods are defined as ``async`` -- see the :ref:`Usage section <async_note>`
+    for more information.
+
+    >>> import asyncio
+    >>> from cool_seq_tool.sources.uta_database import UtaDatabase
+    >>> uta_db = asyncio.run(UtaDatabase.create())
+    """
 
     def __init__(
         self,
@@ -39,19 +49,19 @@ class UTADatabase:
         chain_file_37_to_38: Optional[str] = None,
         chain_file_38_to_37: Optional[str] = None,
     ) -> None:
-        """Initialize DB class. Downstream libraries should use the create()
-        method to construct a new instance: await UTADatabase.create()
+        """Initialize DB class. Should only be used by ``create()`` method, and not
+        be called directly by a user.
 
         :param db_url: PostgreSQL connection URL
-            Format: `driver://user:password@host/database/schema`
+            Format: ``driver://user:password@host/database/schema``
         :param chain_file_37_to_38: Optional path to chain file for 37 to 38 assembly.
-            This is used for pyliftover. 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
-            pyliftover to download a chain file from UCSC
+            This is used for ``pyliftover``. 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 ``pyliftover`` 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 pyliftover. 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
-            pyliftover to download a chain file from UCSC
+            This is used for ``pyliftover``. 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 ``pyliftover`` to download a chain file from UCSC
         """
         self.schema = None
         self._connection_pool = None
@@ -137,10 +147,17 @@ class UTADatabase:
     async def create(
         cls: Type[UTADatabaseType], db_url: str = UTA_DB_URL
     ) -> UTADatabaseType:
-        """Provide fully-initialized class instance (a la factory pattern)
-        :param UTADatabaseType cls: supplied implicitly
-        :param str db_url: PostgreSQL connection URL
-            Format: `driver://user:password@host/database/schema`
+        """Manufacture a fully-initialized class instance (a la factory pattern). This
+        method should be used instead of calling the class directly to create a new
+        instance.
+
+        >>> import asyncio
+        >>> from cool_seq_tool.sources.uta_database import UtaDatabase
+        >>> uta_db = asyncio.run(UtaDatabase.create())
+
+        :param cls: supplied implicitly
+        :param db_url: PostgreSQL connection URL
+            Format: ``driver://user:password@host/database/schema``
         :return: UTA DB access class instance
         """
         self = cls(db_url)
@@ -151,7 +168,7 @@ class UTADatabase:
     async def execute_query(self, query: str) -> Any:  # noqa: ANN401
         """Execute a query and return its result.
 
-        :param str query: Query to make on database
+        :param query: Query to make on database
         :return: Query's result
         """
 
@@ -185,7 +202,7 @@ class UTADatabase:
         genomic_table_exists = genomic_table_exists[0].get("exists")
         if genomic_table_exists is None:
             logger.critical(
-                "SELECT EXISTS query in UTADatabase._create_genomic_table "
+                "SELECT EXISTS query in UtaDatabase._create_genomic_table "
                 "returned invalid response"
             )
             raise ValueError("SELECT EXISTS query returned invalid response")
@@ -212,8 +229,8 @@ class UTADatabase:
             await self.execute_query(create_genomic_table)
 
             indexes = [
-                f"""CREATE INDEX alt_pos_index ON {self.schema}.genomic (alt_ac, alt_start_i, alt_end_i);""",  # noqa: E501
-                f"""CREATE INDEX gene_alt_index ON {self.schema}.genomic (hgnc, alt_ac);""",  # noqa: E501
+                f"""CREATE INDEX alt_pos_index ON {self.schema}.genomic (alt_ac, alt_start_i, alt_end_i);""",
+                f"""CREATE INDEX gene_alt_index ON {self.schema}.genomic (hgnc, alt_ac);""",
                 f"""CREATE INDEX alt_ac_index ON {self.schema}.genomic (alt_ac);""",
             ]
             for create_index in indexes:
@@ -223,7 +240,7 @@ class UTADatabase:
     def _transform_list(li: List) -> List[List[Any]]:
         """Transform list to only contain field values
 
-        :param List li: List of asyncpg.Record objects
+        :param li: List of asyncpg.Record objects
         :return: List of list of objects
         """
         results = list()
@@ -231,30 +248,33 @@ class UTADatabase:
             results.append([field for field in item])
         return results
 
-    async def chr_to_gene_and_accessions(
+    async def get_genes_and_alt_acs(
         self,
-        chromosome: int,
         pos: int,
-        strand: Optional[int] = None,
+        strand: Optional[Strand] = None,
+        chromosome: Optional[int] = None,
         alt_ac: Optional[str] = None,
         gene: Optional[str] = None,
     ) -> Tuple[Optional[Dict], Optional[str]]:
-        """Return genes and genomic accessions related to a position on a chr.
-
-        :param int chromosome: Chromosome number
-        :param int pos: Genomic position
-        :param Optional[int] strand: Strand. Must be either `-1` or `1`
-        :param Optional[str] alt_ac: Genomic accession
-        :param Optional[str] gene: Gene symbol
-        :return: Dictionary containing genes and genomic accessions and
-            warnings if found
+        """Return genes and genomic accessions for a position on a chromosome or alt_ac
+
+        :param pos: Genomic position
+        :param strand: Strand
+        :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 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.
+        :param gene: Gene symbol
+        :return: Dictionary containing genes and genomic accessions and warnings if found
         """
         alt_ac_cond = (
             f"WHERE alt_ac = '{alt_ac}'"
             if alt_ac
             else f"WHERE alt_ac ~ '^NC_[0-9]+0{chromosome}.[0-9]+$'"
         )
-        strand_cond = f"AND alt_strand = '{strand}'" if strand else ""
+        strand_cond = f"AND alt_strand = '{strand.value}'" if strand else ""
         gene_cond = f"AND hgnc = '{gene}'" if gene else ""
 
         query = f"""
@@ -275,7 +295,10 @@ class UTADatabase:
                 f" is mapped between an exon's start and end coordinates"
             )
             if strand:
-                msg += f" on the " f"{'positive' if strand == 1 else 'negative'} strand"
+                msg += (
+                    f" on the "
+                    f"{'positive' if strand == Strand.POSITIVE else 'negative'} strand"
+                )
             if gene:
                 msg += f" and on gene {gene}"
             return None, msg
@@ -293,12 +316,12 @@ class UTADatabase:
     ) -> Tuple[Optional[List[Tuple[int, int]]], Optional[str]]:
         """Get list of transcript exons start/end coordinates.
 
-        :param str tx_ac: Transcript accession
-        :param Optional[str] alt_ac: Genomic accession
+        :param tx_ac: Transcript accession
+        :param alt_ac: Genomic accession
         :return: List of a transcript's accessions and warnings if found
         """
         if alt_ac:
-            # We know what asesmbly we're looking for since we have the
+            # We know what assembly we're looking for since we have the
             # genomic accession
             query = f"""
                 SELECT DISTINCT tx_start_i, tx_end_i
@@ -329,126 +352,17 @@ class UTADatabase:
             tx_exons = [(r["tx_start_i"], r["tx_end_i"]) for r in result]
             return tx_exons, None
 
-    @staticmethod
-    def _validate_exon(
-        transcript: str, tx_exons: List[Tuple[int, int]], exon_number: int
-    ) -> Tuple[Optional[Tuple[int, int]], Optional[str]]:
-        """Validate that exon number is valid
-
-        :param str transcript: Transcript accession
-        :param List tx_exons: List of transcript's exons
-        :param Optional[int] exon_number: Exon number to validate
-        :return: Transcript coordinates and warnings if found
-        """
-        msg = f"Exon {exon_number} does not exist on {transcript}"
-        try:
-            if exon_number < 1:
-                return None, msg
-            exon = tx_exons[exon_number - 1]
-        except IndexError:
-            return None, msg
-        return exon, None
-
-    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],
-    ]:
-        """Get transcript exon coordinates
-
-        :param transcript: Transcript accession
-        :param tx_exons: List of transcript exons
-        :param exon_start: Start exon number
-        :param exon_end: End exon number
-        :return: [Transcript start exon coords, Transcript end exon coords],
-            and warnings if found
-        """
-        if exon_start is not None:
-            tx_exon_start, warning = self._validate_exon(
-                transcript, tx_exons, exon_start
-            )
-            if not tx_exon_start:
-                return None, warning
-        else:
-            tx_exon_start = None
-
-        if exon_end is not None:
-            tx_exon_end, warning = self._validate_exon(transcript, tx_exons, exon_end)
-            if not tx_exon_end:
-                return None, warning
-        else:
-            tx_exon_end = None
-        return (tx_exon_start, tx_exon_end), None
-
-    async def get_alt_ac_start_and_end(
-        self,
-        tx_ac: str,
-        tx_exon_start: Optional[List[str]] = None,
-        tx_exon_end: Optional[List[str]] = None,
-        gene: Optional[str] = None,
-    ) -> Tuple[Optional[Tuple[Tuple, Tuple]], Optional[str]]:
-        """Get genomic coordinates for related transcript exon start and end.
-
-        :param str tx_ac: Transcript accession
-        :param Optional[List[str]] tx_exon_start: Transcript's exon start
-            coordinates
-        :param Optional[List[str]] tx_exon_end: Transcript's exon end
-            coordinates
-        :param str gene: Gene symbol
-        :return: Alt ac start and end data, and warnings if found
-        """
-        if tx_exon_start:
-            alt_ac_start, warning = await self.get_alt_ac_start_or_end(
-                tx_ac, int(tx_exon_start[0]), int(tx_exon_start[1]), gene=gene
-            )
-            if not alt_ac_start:
-                return None, warning
-        else:
-            alt_ac_start = None
-
-        if tx_exon_end:
-            alt_ac_end, warning = await self.get_alt_ac_start_or_end(
-                tx_ac, int(tx_exon_end[0]), int(tx_exon_end[1]), gene=gene
-            )
-            if not alt_ac_end:
-                return None, warning
-        else:
-            alt_ac_end = None
-
-        if alt_ac_start is None and alt_ac_end is None:
-            msg = "Unable to find `alt_ac_start` or `alt_ac_end`"
-            logger.warning(msg)
-            return None, msg
-
-        # validate
-        if alt_ac_start and alt_ac_end:
-            for i in (0, 1, 4):
-                if alt_ac_start[i] != alt_ac_end[i]:
-                    if i == 0:
-                        error = "Gene symbol does not match"
-                    elif i == 1:
-                        error = "Chromosome does not match"
-                    else:
-                        error = "Strand does not match"
-                    logger.warning(f"{error}: " f"{alt_ac_start[i]} != {alt_ac_end[i]}")
-        return (alt_ac_start, alt_ac_end), None
-
     async def get_alt_ac_start_or_end(
         self, tx_ac: str, tx_exon_start: int, tx_exon_end: int, gene: Optional[str]
     ) -> Tuple[Optional[Tuple[str, str, int, int, int]], Optional[str]]:
         """Get genomic data for related transcript exon start or end.
 
-        :param str tx_ac: Transcript accession
-        :param int tx_exon_start: Transcript's exon start coordinate
-        :param int tx_exon_end: Transcript's exon end coordinate
-        :param Optional[str] gene: Gene symbol
+        :param tx_ac: Transcript accession
+        :param tx_exon_start: Transcript's exon start coordinate
+        :param tx_exon_end: Transcript's exon end coordinate
+        :param gene: HGNC gene symbol
         :return: [hgnc symbol, genomic accession for chromosome,
-            start exon's end coordinate, end exon's start coordinate, strand],
+            aligned genomic start coordinate, aligned genomic end coordinate, strand],
             and warnings if found
         """
         if gene:
@@ -487,7 +401,7 @@ class UTADatabase:
     async def get_cds_start_end(self, tx_ac: str) -> Optional[Tuple[int, int]]:
         """Get coding start and end site
 
-        :param str tx_ac: Transcript accession
+        :param tx_ac: Transcript accession
         :return: [Coding start site, Coding end site]
         """
         if tx_ac.startswith("ENS"):
@@ -511,7 +425,7 @@ class UTADatabase:
     async def get_newest_assembly_ac(self, ac: str) -> List[str]:
         """Find accession associated to latest genomic assembly
 
-        :param str ac: Accession
+        :param ac: Accession
         :return: List of accessions associated to latest genomic assembly. Order by
             desc
         """
@@ -540,8 +454,8 @@ class UTADatabase:
     async def validate_genomic_ac(self, ac: str) -> bool:
         """Return whether or not genomic accession exists.
 
-        :param str ac: Genomic accession
-        :return: `True` if genomic accession exists. `False` otherwise.
+        :param ac: Genomic accession
+        :return: ``True`` if genomic accession exists. ``False`` otherwise.
         """
         query = f"""
             SELECT EXISTS(
@@ -554,10 +468,19 @@ class UTADatabase:
         return result[0][0]
 
     async def get_ac_descr(self, ac: str) -> Optional[str]:
-        """Return accession description.
-        Typically description exists if not GRCh38 assembly.
-
-        :param str ac: Accession
+        """Return accession description. This is typically available only for accessions
+        from older (pre-GRCh38) builds.
+
+        >>> import asyncio
+        >>> from cool_seq_tool.sources.uta_database import UtaDatabase
+        >>> async def describe():
+        ...     uta_db = await UtaDatabase.create()
+        ...     result = await uta_db.get_ac_descr("NC_000001.10")
+        ...     return result
+        >>> asyncio.run(describe())
+        'Homo sapiens chromosome 1, GRCh37.p13 Primary Assembly'
+
+        :param ac: chromosome accession, e.g. ``"NC_000001.10"``
         :return: Description containing assembly and chromosome
         """
         query = f"""
@@ -580,23 +503,23 @@ class UTADatabase:
         tx_ac: str,
         start_pos: int,
         end_pos: int,
-        alt_ac: str = None,
+        alt_ac: Optional[str] = None,
         use_tx_pos: bool = True,
         like_tx_ac: bool = False,
     ) -> List:
         """Return queried data from tx_exon_aln_v table.
 
-        :param str tx_ac: accession on c. coordinate
-        :param int start_pos: Start position change
-        :param int end_pos: End position change
-        :param str alt_ac: accession on g. coordinate
-        :param bool use_tx_pos: `True` if querying on transcript position. This means
-            `start_pos` and `end_pos` are on the c. coordinate
-            `False` if querying on genomic position. This means `start_pos` and
-            `end_pos` are on the g. coordinate
-        :param bool like_tx_ac: `True` if tx_ac condition should be a like statement.
+        :param tx_ac: accession on c. coordinate
+        :param start_pos: Start position change
+        :param end_pos: End position change
+        :param alt_ac: accession on g. coordinate
+        :param use_tx_pos: ``True`` if querying on transcript position. This means
+            ``start_pos`` and ``end_pos`` are on the c. coordinate
+            ``False`` if querying on genomic position. This means ``start_pos`` and
+            ``end_pos`` are on the g. coordinate
+        :param like_tx_ac: ``True`` if tx_ac condition should be a like statement.
             This is used when you want to query an accession regardless of its version
-            `False` if tx_condition will be exact match
+            ``False`` if tx_condition will be exact match
         :return: List of tx_exon_aln_v data
         """
         if end_pos is None:
@@ -659,16 +582,13 @@ class UTADatabase:
     def data_from_result(result: List) -> Optional[Dict]:
         """Return data found from result.
 
-        :param List result: Data from tx_exon_aln_v table
+        :param result: Data from tx_exon_aln_v table
         :return: Gene, strand, and position ranges for tx and alt_ac
         """
         gene = result[0]
-        if result[7] == -1:
-            strand = "-"
-        else:
-            strand = "+"
         tx_pos_range = result[2], result[3]
         alt_pos_range = result[5], result[6]
+        strand = Strand(result[7])
         alt_aln_method = result[8]
         tx_exon_id = result[9]
         alt_exon_id = result[10]
@@ -694,13 +614,30 @@ class UTADatabase:
     async def get_mane_c_genomic_data(
         self, ac: str, alt_ac: Optional[str], start_pos: int, end_pos: int
     ) -> Optional[Dict]:
-        """Get MANE Transcript and genomic data.
-
-        Used when going from g -> MANE c
-        :param str ac: MANE Transcript accession
-        :param str alt_ac: NC Accession
-        :param int start_pos: Genomic start position change
-        :param int end_pos: Genomic end position change
+        """Get MANE transcript and genomic data. Used when going from g. to MANE c.
+        representation.
+
+        >>> import asyncio
+        >>> from cool_seq_tool.sources import UtaDatabase
+        >>> async def get_braf_mane():
+        ...     uta_db = await UtaDatabase.create()
+        ...     result = await uta_db.get_mane_c_genomic_data(
+        ...         "NM_004333.6",
+        ...         None,
+        ...         140753335,
+        ...         140753335,
+        ...     )
+        ...     return result
+        >>> braf = asyncio.run(get_braf_mane())
+        >>> braf["alt_ac"]
+        'NC_000007.14'
+
+        :param ac: MANE transcript accession
+        :param alt_ac: NC accession. Used to triangulate on correct genomic data. Can
+            be set to ``None`` if unavailable.
+        :param start_pos: Genomic start position
+        :param end_pos: Genomic end position change
+        :return: MANE transcript results if successful
         """
         results = await self.get_tx_exon_aln_v_data(
             ac, start_pos, end_pos, alt_ac=alt_ac, use_tx_pos=False
@@ -723,9 +660,7 @@ class UTADatabase:
         data["coding_start_site"] = coding_start_site[0]
         data["coding_end_site"] = coding_start_site[1]
 
-        if data["strand"] == "-":
-            end_pos += 1
-            start_pos += 1
+        if data["strand"] == Strand.NEGATIVE:
             data["alt_pos_change_range"] = (end_pos, start_pos)
             data["alt_pos_change"] = (
                 data["alt_pos_range"][1] - data["alt_pos_change_range"][0],
@@ -752,13 +687,12 @@ class UTADatabase:
     ) -> Optional[Dict]:
         """Get transcript mapping to genomic data.
 
-        :param str tx_ac: Accession on c. coordinate
-        :param Tuple pos: (start pos, end pos)
-        :param Union[AnnotationLayer.CDNA, AnnotationLayer.GENOMIC] annotation_layer:
-            Annotation layer for `ac` and `pos`
-        :param Optional[str] alt_ac: Accession on g. coordinate
-        :param Assembly target_genome_assembly: Genome assembly to get genomic data for.
-            If `alt_ac` is provided, it will return the associated assembly.
+        :param tx_ac: Accession on c. coordinate
+        :param pos: (start pos, end pos)
+        :param annotation_layer: Annotation layer for ``ac`` and ``pos``
+        :param alt_ac: Accession on g. coordinate
+        :param target_genome_assembly: Genome assembly to get genomic data for.
+            If ``alt_ac`` is provided, it will return the associated assembly.
         :return: Gene, Transcript accession and position change,
             Altered transcript accession and position change, Strand
         """
@@ -789,7 +723,7 @@ class UTADatabase:
         )
 
         if annotation_layer == AnnotationLayer.CDNA:
-            if data["strand"] == "-":
+            if data["strand"] == Strand.NEGATIVE:
                 data["alt_pos_change_range"] = (
                     data["alt_pos_range"][1] - data["pos_change"][0],
                     data["alt_pos_range"][0] + data["pos_change"][1],
@@ -800,8 +734,8 @@ class UTADatabase:
                     data["alt_pos_range"][1] - data["pos_change"][1],
                 )
         else:
-            if data["strand"] == "-":
-                data["alt_pos_change_range"] = (pos[1] + 1, pos[0] + 1)
+            if data["strand"] == Strand.NEGATIVE:
+                data["alt_pos_change_range"] = (pos[1], pos[0])
             else:
                 data["alt_pos_change_range"] = pos
 
@@ -810,7 +744,7 @@ class UTADatabase:
     async def get_ac_from_gene(self, gene: str) -> List[str]:
         """Return genomic accession(s) associated to a gene.
 
-        :param str gene: Gene symbol
+        :param gene: Gene symbol
         :return: List of genomic accessions, sorted in desc order
         """
         query = f"""
@@ -832,11 +766,20 @@ class UTADatabase:
     async def get_gene_from_ac(
         self, ac: str, start_pos: int, end_pos: int
     ) -> Optional[List[str]]:
-        """Get transcripts from NC accession and positions.
-
-        :param str ac: NC Accession
-        :param int start_pos: Start position change
-        :param int end_pos: End position change
+        """Get gene(s) within the provided coordinate range
+
+        >>> import asyncio
+        >>> from cool_seq_tool.sources import UtaDatabase
+        >>> async def get_gene():
+        ...     uta_db = await UtaDatabase.create()
+        ...     result = await uta_db.get_gene_from_ac("NC_000017.11", 43044296, 43045802)
+        ...     return result
+        >>> asyncio.run(get_gene())
+        ['BRCA1']
+
+        :param ac: NC accession, e.g. ``"NC_000001.11"``
+        :param start_pos: Start position change
+        :param end_pos: End position change
         :return: List of HGNC gene symbols
         """
         if end_pos is None:
@@ -871,20 +814,20 @@ class UTADatabase:
         use_tx_pos: bool = True,
         alt_ac: Optional[str] = None,
     ) -> pl.DataFrame:
-        """Get transcripts for a given `gene` or `alt_ac` related to optional positions.
+        """Get transcripts for a given ``gene`` or ``alt_ac`` related to optional positions.
 
         :param start_pos: Start position change
-            If not provided and `end_pos` not provided, all transcripts associated with
+            If not provided and ``end_pos`` not provided, all transcripts associated with
             the gene and/or accession will be returned
         :param end_pos: End position change
-            If not provided and `start_pos` not provided, all transcripts associated
+            If not provided and ``start_pos`` not provided, all transcripts associated
             with the gene and/or accession will be returned
         :param gene: HGNC gene symbol
-        :param use_tx_pos: `True` if querying on transcript position. This means
-            `start_pos` and `end_pos` are c. coordinate positions. `False` if querying
-            on genomic position. This means `start_pos` and `end_pos` are g. coordinate
+        :param use_tx_pos: ``True`` if querying on transcript position. This means
+            ``start_pos`` and ``end_pos`` are c. coordinate positions. ``False`` if querying
+            on genomic position. This means ``start_pos`` and ``end_pos`` are g. coordinate
             positions
-        :param alt_ac: Genomic accession. If not provided, must provide `gene`
+        :param alt_ac: Genomic accession. If not provided, must provide ``gene``
         :return: Data Frame containing transcripts associated with a gene.
             Transcripts are ordered by most recent NC accession, then by
             descending transcript length
@@ -938,12 +881,15 @@ class UTADatabase:
         results = [
             (r["pro_ac"], r["tx_ac"], r["alt_ac"], r["cds_start_i"]) for r in results
         ]
-        return pl.DataFrame(results, schema=schema).unique()
+        results_df = pl.DataFrame(results, schema=schema)
+        if results:
+            results_df = results_df.unique()
+        return results_df
 
     async def get_chr_assembly(self, ac: str) -> Optional[Tuple[str, str]]:
         """Get chromosome and assembly for NC accession if not in GRCh38.
 
-        :param str ac: NC accession
+        :param ac: NC accession
         :return: Chromosome and Assembly accession is on
         """
         descr = await self.get_ac_descr(ac)
@@ -966,8 +912,8 @@ class UTADatabase:
     async def liftover_to_38(self, genomic_tx_data: Dict) -> None:
         """Liftover genomic_tx_data to hg38 assembly.
 
-        :param Dict genomic_tx_data: Dictionary containing gene, nc_accession,
-            alt_pos, and strand
+        :param genomic_tx_data: Dictionary containing gene, nc_accession, alt_pos, and
+            strand
         """
         descr = await self.get_chr_assembly(genomic_tx_data["alt_ac"])
         if descr is None:
@@ -1022,9 +968,9 @@ class UTADatabase:
     ) -> Optional[Tuple]:
         """Get new genome assembly data for a position on a chromosome.
 
-        :param str chromosome: The chromosome number. Must be prefixed with `chr`
-        :param int pos: Position on the chromosome
-        :param Assembly liftover_to_assembly: Assembly to liftover to
+        :param chromosome: The chromosome number. Must be prefixed with ``chr``
+        :param pos: Position on the chromosome
+        :param liftover_to_assembly: Assembly to liftover to
         :return: [Target chromosome, target position, target strand,
             conversion_chain_score] for assembly
         """
@@ -1055,11 +1001,11 @@ class UTADatabase:
     ) -> None:
         """Update genomic_tx_data to have coordinates for given assembly.
 
-        :param Dict genomic_tx_data: Dictionary containing gene, nc_accession,
-            alt_pos, and strand
-        :param str key: Key to access coordinate positions
-        :param str chromosome: Chromosome, must be prefixed with `chr`
-        :param Assembly liftover_to_assembly: Assembly to liftover to
+        :param genomic_tx_data: Dictionary containing gene, nc_accession, alt_pos, and
+            strand
+        :param key: Key to access coordinate positions
+        :param chromosome: Chromosome, must be prefixed with ``chr``
+        :param liftover_to_assembly: Assembly to liftover to
         """
         liftover_start_i = self.get_liftover(
             chromosome, genomic_tx_data[key][0], liftover_to_assembly
@@ -1084,11 +1030,12 @@ class UTADatabase:
         genomic_tx_data[key] = liftover_start_i[1], liftover_end_i[1]
 
     async def p_to_c_ac(self, p_ac: str) -> List[str]:
-        """Return c. accession from p. accession.
+        """Return cDNA reference sequence accession from protein reference sequence
+        accession (i.e. ``p.`` to ``c.`` in HGVS syntax)
 
-        :param str p_ac: Protein accession
-        :return: List of rows containing c. accessions that are associated
-            with the given p. accession. In ascending order.
+        :param p_ac: Protein accession
+        :return: List of rows containing c. accessions that are associated with the
+            given p. accession. In ascending order.
         """
         # Ensembl accessions do not have versions
         if p_ac.startswith("EN"):
@@ -1115,8 +1062,8 @@ class UTADatabase:
     ) -> List[str]:
         """Get transcripts associated to a genomic ac and position.
 
-        :param str alt_ac: Genomic accession
-        :param int g_pos: Genomic position
+        :param alt_ac: Genomic accession
+        :param g_pos: Genomic position
         :return: RefSeq transcripts on c. coordinate
         """
         query = f"""
@@ -1133,7 +1080,7 @@ class UTADatabase:
 
     @staticmethod
     def get_secret() -> str:
-        """Get secrets for UTA DB instances."""
+        """Get secrets for UTA DB instances. Used for deployment on AWS."""
         secret_name = environ["UTA_DB_SECRET"]
         region_name = "us-east-2"