biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/database/afdb/__init__.py

@@ -0,0 +1,12 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage for downloading predicted protein structures from the AlphaFold DB.
+"""
+
+__name__ = "biotite.database.afdb"
+__author__ = "Alex Carlin"
+
+from .download import *

biotite/database/afdb/download.py

@@ -0,0 +1,197 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.afdb"
+__author__ = "Patrick Kunzmann, Alex Carlin"
+__all__ = ["fetch"]
+
+import io
+import re
+from pathlib import Path
+from xml.etree import ElementTree
+import requests
+from biotite.database.error import RequestError
+
+_METADATA_URL = "https://alphafold.com/api/prediction"
+_BINARY_FORMATS = ["bcif"]
+# Adopted from https://www.uniprot.org/help/accession_numbers
+# adding the optional 'AF-' prefix and '-F1' suffix used by RCSB
+_UNIPROT_PATTERN = (
+    r"^(?P<prefix>(AF-)|(AF_AF))?"
+    r"(?P<id>[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2})"
+    r"(?P<suffix>-?F1)?$"
+)
+
+
+def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
+    """
+    Download predicted protein structures from the AlphaFold DB.
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    ids : str or iterable object of str
+        A single ID or a list of IDs of the file(s) to be downloaded.
+        They can be either UniProt IDs (e.g. ``P12345``), AlphaFold DB IDs
+        (e.g. ``AF-P12345-F1``) or computational RCSB IDs (e.g. ``AF_AFP12345F1``).
+    format : {'pdb', 'pdbx', 'cif', 'mmcif', 'bcif', 'fasta'}
+        The format of the files to be downloaded.
+    target_path : str, optional
+        The target directory of the downloaded files.
+        By default, the file content is stored in a file-like object
+        (`StringIO` or `BytesIO`, respectively).
+    overwrite : bool, optional
+        If true, existing files will be overwritten.
+        Otherwise the respective file will only be downloaded if the file does not
+        exist yet in the specified target directory or if the file is empty.
+    verbose : bool, optional
+        If true, the function will output the download progress.
+
+    Returns
+    -------
+    files : str or StringIO or BytesIO or list of (str or StringIO or BytesIO)
+        The file path(s) to the downloaded files.
+        If a single string (a single ID) was given in `ids`, a single string is
+        returned.
+        If a list (or other iterable object) was given, a list of strings is returned.
+        If no `target_path` was given, the file contents are stored in either
+        ``StringIO`` or ``BytesIO`` objects.
+
+    Examples
+    --------
+
+    >>> from pathlib import Path
+    >>> file = fetch("P12345", "cif", path_to_directory)
+    >>> print(Path(file).name)
+    P12345.cif
+    >>> files = fetch(["P12345", "Q8K9I1"], "cif", path_to_directory)
+    >>> print([Path(file).name for file in files])
+    ['P12345.cif', 'Q8K9I1.cif']
+    """
+    if format not in ["pdb", "pdbx", "cif", "mmcif", "bcif", "fasta"]:
+        raise ValueError(f"Format '{format}' is not supported")
+    if format in ["pdbx", "mmcif"]:
+        format = "cif"
+
+    # If only a single ID is present,
+    # put it into a single element list
+    if isinstance(ids, str):
+        ids = [ids]
+        single_element = True
+    else:
+        single_element = False
+    if target_path is not None:
+        target_path = Path(target_path)
+        target_path.mkdir(parents=True, exist_ok=True)
+
+    files = []
+    for i, id in enumerate(ids):
+        # Verbose output
+        if verbose:
+            print(f"Fetching file {i + 1:d} / {len(ids):d} ({id})...", end="\r")
+        # Fetch file from database
+        if target_path is not None:
+            file = target_path / f"{id}.{format}"
+        else:
+            # 'file = None' -> store content in a file-like object
+            file = None
+        if file is None or not file.is_file() or file.stat().st_size == 0 or overwrite:
+            file_response = requests.get(_get_file_url(id, format))
+            _assert_valid_file(file_response, id)
+            if format in _BINARY_FORMATS:
+                content = file_response.content
+            else:
+                content = file_response.text
+
+            if file is None:
+                if format in _BINARY_FORMATS:
+                    file = io.BytesIO(content)
+                else:
+                    file = io.StringIO(content)
+            else:
+                mode = "wb+" if format in _BINARY_FORMATS else "w+"
+                with open(file, mode) as f:
+                    f.write(content)
+
+        files.append(file)
+    if verbose:
+        print("\nDone")
+
+    # Return paths as strings
+    files = [file.as_posix() if isinstance(file, Path) else file for file in files]
+    # If input was a single ID, return only a single element
+    if single_element:
+        return files[0]
+    else:
+        return files
+
+
+def _get_file_url(id, format):
+    """
+    Get the actual file URL for the given ID from the ``prediction`` API endpoint.
+
+    Parameters
+    ----------
+    id : str
+        The ID of the file to be downloaded.
+    format : str
+        The format of the file to be downloaded.
+
+    Returns
+    -------
+    file_url : str
+        The URL of the file to be downloaded.
+    """
+    uniprot_id = _extract_id(id)
+    try:
+        metadata = requests.get(f"{_METADATA_URL}/{uniprot_id}").json()
+    except requests.exceptions.JSONDecodeError:
+        raise RequestError("Received malformed JSON response")
+    if len(metadata) == 0:
+        raise RequestError(f"ID {id} is invalid")
+    # A list of length 1 is always returned, if the response is valid
+    return metadata[0][f"{format}Url"]
+
+
+def _extract_id(id):
+    """
+    Extract a AFDB compatible UniProt ID from the given qualifier.
+    This may comprise
+
+    - Directly the UniProt ID (e.g. ``P12345``) (trivial case)
+    - Entry ID, as also returned by the RCSB search API (e.g. ``AF-P12345-F1``)
+
+    Parameters
+    ----------
+    id : str
+        The qualifier to extract the UniProt ID from.
+
+    Returns
+    -------
+    uniprot_id : str
+        The UniProt ID.
+    """
+    match = re.match(_UNIPROT_PATTERN, id)
+    if match is None:
+        raise ValueError(f"Cannot extract AFDB identifier from '{id}'")
+    return match.group("id")
+
+
+def _assert_valid_file(response, id):
+    """
+    Checks whether the response is an actual structure file
+    or the response a *404* error due to invalid UniProt ID.
+    """
+    if len(response.text) == 0:
+        raise RequestError(f"Received no repsone for '{id}'")
+    try:
+        root = ElementTree.fromstring(response.text)
+        if root.tag == "Error":
+            raise RequestError(
+                f"Error while fetching '{id}': {root.find('Message').text}"
+            )
+    except ElementTree.ParseError:
+        # This is not XML -> the response is probably a valid file
+        pass

biotite/database/entrez/__init__.py

@@ -0,0 +1,15 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage for downloading files from the NCBI Entrez database.
+"""
+
+__name__ = "biotite.database.entrez"
+__author__ = "Patrick Kunzmann"
+
+from .dbnames import *
+from .download import *
+from .key import *
+from .query import *

biotite/database/entrez/check.py

@@ -0,0 +1,60 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.entrez"
+__author__ = "Patrick Kunzmann, Maximilian Dombrowsky"
+__all__ = ["check_for_errors"]
+
+import json
+from biotite.database.error import RequestError
+
+# Taken from https://github.com/kblin/ncbi-entrez-error-messages
+_error_messages = [
+    "Error reading from remote server",
+    "Bad gateway",
+    "Bad Gateway",
+    "Cannot process ID list",
+    "server is temporarily unable to service your request",
+    "Service unavailable",
+    "Server Error",
+    "ID list is empty",
+    "Supplied id parameter is empty",
+    "Resource temporarily unavailable",
+    "Failed to retrieve sequence",
+    "Failed to understand id",
+]
+
+
+def check_for_errors(message):
+    """
+    Check for common error messages in NCBI Entrez database responses.
+
+    Parameters
+    ----------
+    message : str
+        The message received from NCBI Entrez.
+
+    Raises
+    ------
+    RequestError
+        If the message contains an error message.
+    """
+    # Server can respond short JSON error messages
+    if len(message) < 500:
+        try:
+            message_json = json.loads(message)
+            if "error" in message_json:
+                raise RequestError(message_json["error"])
+        except json.decoder.JSONDecodeError:
+            # It is not a JSON message
+            pass
+
+    # Error always appear at the end of message
+    message_end = message[-200:]
+    # Seemingly arbitrary '+' characters are in NCBI error messages
+    message_end = message_end.replace("+", "")
+    for error_msg in _error_messages:
+        # Often whitespace is also replaced by '+' in error message
+        if error_msg.replace(" ", "") in message_end:
+            raise RequestError(error_msg)

biotite/database/entrez/dbnames.py

@@ -0,0 +1,101 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.entrez"
+__author__ = "Patrick Kunzmann"
+__all__ = ["get_database_name"]
+
+
+# fmt: off
+_db_names = {
+    "BioProject"        : "bioproject",
+    "BioSample"         : "biosample",
+    "Biosystems"        : "biosystems",
+    "Books"             : "books",
+    "Conserved Domains" : "cdd",
+    "dbGaP"             : "gap",
+    "dbVar"             : "dbvar",
+    "Epigenomics"       : "epigenomics",
+    "EST"               : "nucest",
+    "Gene"              : "gene",
+    "Genome"            : "genome",
+    "GEO Datasets"      : "gds",
+    "GEO Profiles"      : "geoprofiles",
+    "GSS"               : "nucgss",
+    "HomoloGene"        : "homologene",
+    "MeSH"              : "mesh",
+    "NCBI C++ Toolkit"  : "toolkit",
+    "NCBI Web Site"     : "ncbisearch",
+    "NLM Catalog"       : "nlmcatalog",
+    "Nucleotide"        : "nuccore",
+    "OMIA"              : "omia",
+    "PopSet"            : "popset",
+    "Probe"             : "probe",
+    "Protein"           : "protein",
+    "Protein Clusters"  : "proteinclusters",
+    "PubChem BioAssay"  : "pcassay",
+    "PubChem Compound"  : "pccompound",
+    "PubChem Substance" : "pcsubstance",
+    "PubMed"            : "pubmed",
+    "PubMed Central"    : "pmc",
+    "SNP"               : "snp",
+    "SRA"               : "sra",
+    "Structure"         : "structure",
+    "Taxonomy"          : "taxonomy",
+    "UniGene"           : "unigene",
+    "UniSTS"            : "unists"
+}
+# fmt: on
+
+
+def get_database_name(database):
+    """
+    Map a common NCBI Entrez database name to an E-utility database
+    name.
+
+    Parameters
+    ----------
+    database : str
+        Entrez database name.
+
+    Returns
+    -------
+    name : str
+        E-utility database name.
+
+    Examples
+    --------
+
+    >>> print(get_database_name("Nucleotide"))
+    nuccore
+    """
+    return _db_names[database]
+
+
+def sanitize_database_name(db_name):
+    """
+    Map a common NCBI Entrez database name to an E-utility database
+    name, return E-utility database name, or raise an exception if the
+    database name is not existing.
+
+    Only for internal usage in ``download.py`` and ``query.py``.
+
+    Parameters
+    ----------
+    db_name : str
+        Entrez database name.
+
+    Returns
+    -------
+    name : str
+        E-utility database name.
+    """
+    if db_name in _db_names.keys():
+        # Convert into E-utility database name
+        return _db_names[db_name]
+    elif db_name in _db_names.values():
+        # Is already E-utility database name
+        return db_name
+    else:
+        raise ValueError("Database '{db_name}' is not existing")

biotite/database/entrez/download.py

@@ -0,0 +1,228 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.entrez"
+__author__ = "Patrick Kunzmann"
+__all__ = ["fetch", "fetch_single_file"]
+
+import io
+import os
+from os.path import getsize, isdir, isfile, join
+import requests
+from biotite.database.entrez.check import check_for_errors
+from biotite.database.entrez.dbnames import sanitize_database_name
+from biotite.database.entrez.key import get_api_key
+from biotite.database.error import RequestError
+
+_fetch_url = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi"
+
+
+def fetch(
+    uids,
+    target_path,
+    suffix,
+    db_name,
+    ret_type,
+    ret_mode="text",
+    overwrite=False,
+    verbose=False,
+):
+    """
+    Download files from the NCBI Entrez database in various formats.
+
+    The data for each UID will be fetched into a separate file.
+
+    A list of valid database, retrieval type and mode combinations can
+    be found under
+    `<https://www.ncbi.nlm.nih.gov/books/NBK25499/table/chapter4.T._valid_values_of__retmode_and/?report=objectonly>`_
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    uids : str or iterable object of str
+        A single *unique identifier* (UID) or a list of UIDs of the
+        file(s) to be downloaded.
+    target_path : str or None
+        The target directory of the downloaded files.
+        If ``None``, the file content is stored in a file-like object
+        (`StringIO` or `BytesIO`, respectively).
+    suffix : str
+        The file suffix of the downloaded files. This value is
+        independent of the retrieval type.
+    db_name : str:
+        E-utility or common database name.
+    ret_type : str
+        Retrieval type.
+    ret_mode : str, optional
+        Retrieval mode.
+    overwrite : bool, optional
+        If true, existing files will be overwritten. Otherwise the
+        respective file will only be downloaded if the file does not
+        exist yet in the specified target directory or if the file is
+        empty.
+    verbose : bool, optional
+        If true, the function will output the download progress.
+
+    Returns
+    -------
+    files : str or StringIO or BytesIO or list of (str or StringIO or BytesIO)
+        The file path(s) to the downloaded files.
+        If a single string (a single UID) was given in `uids`,
+        a single string is returned. If a list (or other iterable
+        object) was given, a list of strings is returned.
+        If `target_path` is ``None``, the file contents are stored in
+        either `StringIO` or `BytesIO` objects.
+
+    Warnings
+    --------
+    Even if you give valid input to this function, in rare cases the
+    database might return no or malformed data to you.
+    In these cases the request should be retried.
+    When the issue occurs repeatedly, the error is probably in your
+    input.
+
+    See Also
+    --------
+    fetch_single_file : Fetch multiple entries as a single file.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> files = fetch(["1L2Y_A","3O5R_A"], path_to_directory, suffix="fa",
+    ...               db_name="protein", ret_type="fasta")
+    >>> print([os.path.basename(file) for file in files])
+    ['1L2Y_A.fa', '3O5R_A.fa']
+    """
+    # If only a single UID is present,
+    # put it into a single element list
+    if isinstance(uids, str):
+        uids = [uids]
+        single_element = True
+    else:
+        single_element = False
+    # Create the target folder, if not existing
+    if target_path is not None and not isdir(target_path):
+        os.makedirs(target_path)
+    files = []
+    for i, id in enumerate(uids):
+        # Verbose output
+        if verbose:
+            print(f"Fetching file {i + 1:d} / {len(uids):d} ({id})...", end="\r")
+        # Fetch file from database
+        if target_path is not None:
+            file = join(target_path, id + "." + suffix)
+        else:
+            file = None
+        if file is None or not isfile(file) or getsize(file) == 0 or overwrite:
+            param_dict = {
+                "db": sanitize_database_name(db_name),
+                "id": id,
+                "rettype": ret_type,
+                "retmode": ret_mode,
+                "tool": "Biotite",
+                "mail": "padix.key@gmail.com",
+            }
+            api_key = get_api_key()
+            if api_key is not None:
+                param_dict["api_key"] = api_key
+            r = requests.get(_fetch_url, params=param_dict)
+            content = r.text
+            check_for_errors(content)
+            if content.startswith(" Error"):
+                raise RequestError(content[8:])
+            if file is None:
+                file = io.StringIO(content)
+            else:
+                with open(file, "w+") as f:
+                    f.write(content)
+        files.append(file)
+    if verbose:
+        print("\nDone")
+    # If input was a single ID, return only a single path
+    if single_element:
+        return files[0]
+    else:
+        return files
+
+
+def fetch_single_file(
+    uids, file_name, db_name, ret_type, ret_mode="text", overwrite=False
+):
+    """
+    Almost the same as :func:`fetch()`, but the data for the given UIDs
+    will be stored in a single file.
+
+    Parameters
+    ----------
+    uids : iterable object of str
+        A list of UIDs of the
+        file(s) to be downloaded.
+    file_name : str or None
+        The file path, including file name, to the target file.
+    db_name : str:
+        E-utility or common database name.
+    ret_type : str
+        Retrieval type.
+    ret_mode : str, optional
+        Retrieval mode.
+    overwrite : bool, optional
+        If false, the file is only downloaded, if no file with the same
+        name already exists.
+
+    Returns
+    -------
+    file : str or StringIO or BytesIO
+        The file name of the downloaded file.
+        If `file_name` is ``None``, the file content is stored in
+        either a `StringIO` or a `BytesIO` object.
+
+    Warnings
+    --------
+    Even if you give valid input to this function, in rare cases the
+    database might return no or malformed data to you.
+    In these cases the request should be retried.
+    When the issue occurs repeatedly, the error is probably in your
+    input.
+
+    See Also
+    --------
+    fetch : Fetch one or multiple entries as separate files.
+    """
+    if (
+        file_name is not None
+        and os.path.isfile(file_name)
+        and getsize(file_name) > 0
+        and not overwrite
+    ):
+        # Do no redownload the already existing file
+        return file_name
+    uid_list_str = ""
+    for id in uids:
+        uid_list_str += id + ","
+    # Remove terminal comma
+    uid_list_str = uid_list_str[:-1]
+    param_dict = {
+        "db": sanitize_database_name(db_name),
+        "id": uid_list_str,
+        "rettype": ret_type,
+        "retmode": ret_mode,
+        "tool": "Biotite",
+        "mail": "padix.key@gmail.com",
+    }
+    api_key = get_api_key()
+    if api_key is not None:
+        param_dict["api_key"] = api_key
+    r = requests.get(_fetch_url, params=param_dict)
+    content = r.text
+    check_for_errors(content)
+    if content.startswith(" Error"):
+        raise RequestError(content[8:])
+    if file_name is None:
+        return io.StringIO(content)
+    else:
+        with open(file_name, "w+") as f:
+            f.write(content)
+        return file_name

biotite/database/entrez/key.py

@@ -0,0 +1,44 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.entrez"
+__author__ = "Patrick Kunzmann"
+__all__ = ["set_api_key", "get_api_key"]
+
+
+_API_KEY = None
+
+
+def get_api_key():
+    """
+    Get the
+    `NCBI API key <https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/>`_.
+
+    Returns
+    -------
+    api_key : str or None
+        The API key, if it was already set before, ``None`` otherwise.
+    """
+    global _API_KEY
+    return _API_KEY
+
+
+def set_api_key(key):
+    """
+    Set the
+    `NCBI API key <https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/>`_.
+
+    Using an API key increases the request limit on the NCBI servers
+    and is automatically used by functions in
+    :mod:`biotite.database.entrez`.
+    This key is kept only in memory and hence removed in the end of the
+    Python session.
+
+    Parameters
+    ----------
+    key : str
+        The API key.
+    """
+    global _API_KEY
+    _API_KEY = key