biotite 1.5.0__cp314-cp314-macosx_10_13_x86_64.whl

biotite/database/entrez/query.py

@@ -0,0 +1,263 @@
+# 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__ = ["Query", "SimpleQuery", "CompositeQuery", "search"]
+
+import abc
+from xml.etree import ElementTree
+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
+
+_search_url = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi"
+
+
+class Query(metaclass=abc.ABCMeta):
+    """
+    Base class for a wrapper around a search term
+    for the NCBI Entrez search service.
+    """
+
+    def __init__(self):
+        pass
+
+    @abc.abstractmethod
+    def __str__(self):
+        pass
+
+    def __or__(self, operand):
+        if not isinstance(operand, Query):
+            operand = SimpleQuery(operand)
+        return CompositeQuery("OR", self, operand)
+
+    def __and__(self, operand):
+        if not isinstance(operand, Query):
+            operand = SimpleQuery(operand)
+        return CompositeQuery("AND", self, operand)
+
+    def __xor__(self, operand):
+        if not isinstance(operand, Query):
+            operand = SimpleQuery(operand)
+        return CompositeQuery("NOT", self, operand)
+
+
+class CompositeQuery(Query):
+    """
+    A representation of an composite query
+    for the NCBI Entrez search service.
+
+    A composite query is a combination of two other queries,
+    combined either with an 'AND', 'OR' or 'NOT' operator.
+
+    Usually the user does not create instances of this class directly,
+    but :class:`Query` instances are combined with
+    ``|`` (OR), ``&`` (AND) or ``^`` (NOT).
+
+    Parameters
+    ----------
+    operator : str, {"AND", "OR", "NOT"}
+        The combination operator.
+    query1, query2 : SimpleQuery
+        The queries to be combined.
+
+    Examples
+    --------
+
+    >>> query = SimpleQuery("Escherichia coli", "Organism") & \\
+    ... SimpleQuery("90:100", "Sequence Length")
+    >>> print(type(query).__name__)
+    CompositeQuery
+    >>> print(query)
+    ("Escherichia coli"[Organism]) AND (90:100[Sequence Length])
+    """
+
+    def __init__(self, operator, query1, query2):
+        super().__init__()
+        self._op = operator
+        self._q1 = query1
+        self._q2 = query2
+
+    def __str__(self):
+        return "({:}) {:} ({:})".format(str(self._q1), self._op, self._q2)
+
+
+class SimpleQuery(Query):
+    """
+    A simple query for the NCBI Entrez search service without
+    combination via 'AND', 'OR' or 'NOT'. A query consists of a search
+    term and an optional field.
+
+    A list of available search fields with description can be found
+    `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
+
+    Parameters
+    ----------
+    term : str
+        The search term.
+    field : str, optional
+        The field to search the term in.
+        The list of possible fields and the required search term
+        formatting can be found
+        `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
+        By default the field is omitted and all fields are searched in
+        for the term, implicitly.
+
+    Examples
+    --------
+
+    >>> query = SimpleQuery("Escherichia coli")
+    >>> print(query)
+    "Escherichia coli"
+    >>> query = SimpleQuery("Escherichia coli", "Organism")
+    >>> print(query)
+    "Escherichia coli"[Organism]
+    """
+
+    # Field identifiers are taken from
+    # https://www.ncbi.nlm.nih.gov/books/NBK49540/
+    _fields = [
+        "Accession",
+        "All Fields",
+        "Author",
+        "EC/RN Number",
+        "Feature Key",
+        "Filter",
+        "Gene Name",
+        "Genome Project",
+        "Issue",
+        "Journal",
+        "Keyword",
+        "Modification Date",
+        "Molecular Weight",
+        "Organism",
+        "Page Number",
+        "Primary Accession",
+        "Properties",
+        "Protein Name",
+        "Publication Date",
+        "SeqID String",
+        "Sequence Length",
+        "Substance Name",
+        "Text Word",
+        "Title",
+        "Volume",
+        # Abbreviations
+        "ACCN",
+        "ALL",
+        "AU",
+        "AUTH",
+        "ECNO",
+        "FKEY",
+        "FILT",
+        "SB",
+        "GENE",
+        "ISS",
+        "JOUR",
+        "KYWD",
+        "MDAT",
+        "MOLWT",
+        "ORGN",
+        "PAGE",
+        "PACC",
+        "PORGN",
+        "PROP",
+        "PROT",
+        "PDAT",
+        "SQID",
+        "SLEN",
+        "SUBS",
+        "WORD",
+        "TI",
+        "TITL",
+        "VOL",
+    ]
+
+    def __init__(self, term, field=None):
+        super().__init__()
+        if field is not None:
+            if field not in SimpleQuery._fields:
+                raise ValueError(f"Unknown field identifier '{field}'")
+        for invalid_string in ['"', "AND", "OR", "NOT", "[", "]", "(", ")", "\t", "\n"]:
+            if invalid_string in term:
+                raise ValueError(f"Query contains illegal term {invalid_string}")
+        if " " in term:
+            # Encapsulate in quotes if spaces are in search term
+            term = f'"{term}"'
+        self._term = term
+        self._field = field
+
+    def __str__(self):
+        string = self._term
+        if self._field is not None:
+            string += f"[{self._field}]"
+        return string
+
+
+def search(query, db_name, number=20):
+    r"""
+    Get all PDB IDs that meet the given query requirements,
+    via the NCBI ESearch service.
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    query : Query
+        The search query.
+    db_name : str:
+        E-utility or common database name.
+    number : Query
+        The maximum number of UIDs that are obtained.
+
+    Returns
+    -------
+    ids : list of str
+        A list of strings containing all NCBI UIDs (accession number)
+        that meet the query requirements.
+
+    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.
+
+    Notes
+    -----
+    A list of available search fields with description can be found
+    `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
+
+    Examples
+    --------
+    >>> query = SimpleQuery("Escherichia coli", "Organism") & \
+    ...         SimpleQuery("90:100", "Sequence Length")
+    >>> ids = search(query, "nuccore", number=5)
+    >>> print(ids)
+    ['...', '...', '...', '...', '...']
+    """
+    param_dict = {
+        "db": sanitize_database_name(db_name),
+        "term": str(query),
+        "retmax": str(number),
+    }
+    api_key = get_api_key()
+    if api_key is not None:
+        param_dict["api_key"] = api_key
+    r = requests.get(_search_url, params=param_dict)
+    xml_response = r.text
+    check_for_errors(xml_response)
+    try:
+        root = ElementTree.fromstring(xml_response)
+    except ElementTree.ParseError:
+        if len(xml_response) > 100:
+            xml_response = xml_response[:100] + "..."
+        raise RequestError(f"Invalid server response: {xml_response}")
+    xpath = ".//IdList/Id"
+    uids = [element.text for element in root.findall(xpath)]
+    return uids

biotite/database/error.py

@@ -0,0 +1,16 @@
+# 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"
+__author__ = "Patrick Kunzmann"
+__all__ = ["RequestError"]
+
+
+class RequestError(Exception):
+    """
+    Indicates that the database returned a response with an error
+    message or other malformed content.
+    """
+
+    pass

biotite/database/pubchem/__init__.py

@@ -0,0 +1,21 @@
+# 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 searching and downloading files from the *PubChem*
+database.
+Although *PubChem* is part of *NCBI Entrez*,
+:mod:`biotite.database.entrez` is only capable of accessing
+meta-information from *PubChem*.
+This subpackage, on the other hand, supports searching *PubChem*
+compounds based on chemical information and is able to download
+structure records.
+"""
+
+__name__ = "biotite.database.pubchem"
+__author__ = "Patrick Kunzmann"
+
+from .download import *
+from .query import *
+from .throttle import *

biotite/database/pubchem/download.py

@@ -0,0 +1,258 @@
+# 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.pubchem"
+__author__ = "Patrick Kunzmann"
+__all__ = ["fetch", "fetch_property"]
+
+import io
+import numbers
+import os
+from os.path import getsize, isdir, isfile, join
+import requests
+from biotite.database.error import RequestError
+from biotite.database.pubchem.error import parse_error_details
+from biotite.database.pubchem.throttle import ThrottleStatus
+
+_base_url = "https://pubchem.ncbi.nlm.nih.gov/rest/pug/"
+_binary_formats = ["png", "asnb"]
+
+
+def fetch(
+    cids,
+    format="sdf",
+    target_path=None,
+    as_structural_formula=False,
+    overwrite=False,
+    verbose=False,
+    throttle_threshold=0.5,
+    return_throttle_status=False,
+):
+    """
+    Download structure files from *PubChem* in various formats.
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    cids : int or iterable object or int
+        A single compound ID (CID) or a list of CIDs of the structure(s)
+        to be downloaded.
+    format : {'sdf', 'asnt' 'asnb', 'xml', 'json', 'jsonp', 'png'}
+        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
+        (:class:`StringIO` or :class:`BytesIO`, respectively).
+    as_structural_formula : bool, optional
+        If set to true, the structural formula is download instead of
+        an 3D conformer.
+        This means that coordinates lie in th xy-plane and represent
+        the positions atoms would have an a structural formula
+        representation.
+    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 set to true, the function will output the download progress.
+    throttle_threshold : float or None, optional
+        A value between 0 and 1.
+        If the load of either the request time or count exceeds this
+        value the execution is halted.
+        See :class:`ThrottleStatus` for more information.
+        If ``None`` is given, the execution is never halted.
+    return_throttle_status : float, optional
+        If set to true, the :class:`ThrottleStatus` of the final request
+        is also returned.
+
+    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 CID was given in `cids`,
+        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 :class:`StringIO` or :class:`BytesIO` objects.
+    throttle_status : ThrottleStatus
+        The :class:`ThrottleStatus` obtained from the server response.
+        If multiple CIDs are requested, the :class:`ThrottleStatus` of
+        of the final response is returned.
+        This can be used for custom request throttling, for example.
+        Only returned, if `return_throttle_status` is set to true.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = fetch(2244, "sdf", path_to_directory)
+    >>> print(os.path.basename(file))
+    2244.sdf
+    >>> files = fetch([2244, 5950], "sdf", path_to_directory)
+    >>> print([os.path.basename(file) for file in files])
+    ['2244.sdf', '5950.sdf']
+    """
+    # If only a single CID is present,
+    # put it into a single element list
+    if isinstance(cids, numbers.Integral):
+        cids = [cids]
+        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, cid in enumerate(cids):
+        # Prevent IDs as strings, this could be a common error, as other
+        # database interfaces of Biotite use string IDs
+        if isinstance(cid, str):
+            raise TypeError("CIDs must be given as integers, not as string")
+        # Verbose output
+        if verbose:
+            print(f"Fetching file {i + 1:d} / {len(cids):d} ({cid})...", end="\r")
+
+        # Fetch file from database
+        if target_path is not None:
+            file = join(target_path, str(cid) + "." + format)
+        else:
+            # 'file = None' -> store content in a file-like object
+            file = None
+
+        if file is None or not isfile(file) or getsize(file) == 0 or overwrite:
+            record_type = "2d" if as_structural_formula else "3d"
+            r = requests.get(
+                _base_url + f"compound/cid/{cid}/{format.upper()}",
+                params={"record_type": record_type},
+            )
+            if not r.ok:
+                raise RequestError(parse_error_details(r.text))
+
+            if format.lower() in _binary_formats:
+                content = r.content
+            else:
+                content = r.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)
+
+            throttle_status = ThrottleStatus.from_response(r)
+            if throttle_threshold is not None:
+                throttle_status.wait_if_busy(throttle_threshold)
+
+        files.append(file)
+    if verbose:
+        print("\nDone")
+    # If input was a single ID, return only a single path
+    if single_element:
+        return_value = files[0]
+    else:
+        return_value = files
+    if return_throttle_status:
+        return return_value, throttle_status
+    else:
+        return return_value
+
+
+def fetch_property(cids, name, throttle_threshold=0.5, return_throttle_status=False):
+    """
+    Download the given property for the given CID(s).
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    cids : int or iterable object or int
+        A single compound ID (CID) or a list of CIDs to get the property
+        for.
+    name : str
+        The name of the desired property.
+        Valid properties are given in the *PubChem* REST API
+        `documentation <https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest#section=Compound-Property-Tables>`_.
+    throttle_threshold : float or None, optional
+        A value between 0 and 1.
+        If the load of either the request time or count exceeds this
+        value the execution is halted.
+        See :class:`ThrottleStatus` for more information.
+        If ``None`` is given, the execution is never halted.
+    return_throttle_status : float, optional
+        If set to true, the :class:`ThrottleStatus` of the final request
+        is also returned.
+
+    Returns
+    -------
+    property : str or list of str
+        The requested property for each given CID.
+        If a single CID was given in `cids`,
+        a single string is returned.
+        If a list (or other iterable
+        object) was given, a list of strings is returned.
+    throttle_status : ThrottleStatus
+        The :class:`ThrottleStatus` obtained from the server response.
+        This can be used for custom request throttling, for example.
+        Only returned, if `return_throttle_status` is set to true.
+
+    Examples
+    --------
+
+    >>> butane_cids = np.array(search(FormulaQuery("C4H10")))
+    >>> # Filter natural isotopes...
+    >>> n_iso = np.array(fetch_property(butane_cids, "IsotopeAtomCount"), dtype=int)
+    >>> # ...and neutral compounds
+    >>> charge = np.array(fetch_property(butane_cids, "Charge"), dtype=int)
+    >>> butane_cids = butane_cids[(n_iso == 0) & (charge == 0)]
+    >>> print(sorted(butane_cids.tolist()))
+    [6360, 7843, 18402699, 19029854, 19048342, 157632982, 158271732, 158934736, 161295599, 161897780]
+    >>> # Get the IUPAC names for each compound
+    >>> iupac_names = fetch_property(butane_cids, "IUPACName")
+    >>> # Compounds with multiple molecules use ';' as separator
+    >>> print(iupac_names)
+    ['butane', '2-methylpropane', 'methane;prop-1-ene', 'ethane;ethene', 'cyclopropane;methane', 'cyclobutane;molecular hydrogen', 'acetylene;methane', 'carbanide;propane', 'carbanylium;propane', 'methylcyclopropane;molecular hydrogen']
+    """
+    # If only a single CID is present,
+    # put it into a single element list
+    if isinstance(cids, numbers.Integral):
+        cids = [cids]
+        single_element = True
+    else:
+        single_element = False
+
+    # Property names may only contain letters and numbers
+    if not name.isalnum():
+        raise ValueError(f"Property '{name}' contains invalid characters")
+
+    # Use TXT format instead of CSV to avoid issues with ',' characters
+    # within table elements
+    r = requests.post(
+        _base_url + f"compound/cid/property/{name}/TXT",
+        data={"cid": ",".join([str(cid) for cid in cids])},
+    )
+    if not r.ok:
+        raise RequestError(parse_error_details(r.text))
+    throttle_status = ThrottleStatus.from_response(r)
+    if throttle_threshold is not None:
+        throttle_status.wait_if_busy(throttle_threshold)
+
+    # Each line contains the property for one CID
+    properties = r.text.splitlines()
+
+    # If input was a single ID, return only a single value
+    if single_element:
+        return_value = properties[0]
+    else:
+        return_value = properties
+    if return_throttle_status:
+        return return_value, throttle_status
+    else:
+        return return_value

biotite/database/pubchem/error.py

@@ -0,0 +1,30 @@
+# 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.pubchem"
+__author__ = "Patrick Kunzmann"
+__all__ = ["parse_error_details"]
+
+
+def parse_error_details(response_text):
+    """
+    Parse the ``Detail: ...`` or alternatively ``Message: ...`` part of
+    an error response.
+
+    Parameters
+    ----------
+    response_text : str
+        The text of the response.
+
+    Returns
+    -------
+    error_details : str
+        The error details.
+    """
+    for message_line_indicator in ["Detail: ", "Message: "]:
+        for line in response_text.splitlines():
+            if line.startswith(message_line_indicator):
+                return line[len(message_line_indicator) :]
+    # No 'Detail: ...' or 'Message: ' line found
+    return "Unknown error"