biotite 1.1.0__cp311-cp311-macosx_11_0_arm64.whl → 1.3.0__cp311-cp311-macosx_11_0_arm64.whl

biotite/application/application.py

@@ -157,7 +157,7 @@ class Application(metaclass=abc.ABCMeta):
             if timeout is not None and time.time() - self._start_time > timeout:
                 self.cancel()
                 raise TimeoutError(
-                    f"The application expired its timeout " f"({timeout:.1f} s)"
+                    f"The application expired its timeout ({timeout:.1f} s)"
                 )
             else:
                 time.sleep(self.wait_interval())
@@ -214,7 +214,7 @@ class Application(metaclass=abc.ABCMeta):
         Returns
         -------
         finished : bool
-            True of the application has finished, false otherwise
+            True of the application has finished, false otherwise.
         """
         pass
 
@@ -230,7 +230,7 @@ class Application(metaclass=abc.ABCMeta):
         -------
         interval : float
             Time (in seconds) between calls of :func:`is_finished()` in
-            :func:`join()`
+            :func:`join()`.
         """
         pass
 

biotite/application/autodock/app.py

@@ -153,7 +153,7 @@ class VinaApp(LocalApp):
 
         Parameters
         ----------
-        number : float
+        energy_range : float
             The energy range (kcal/mol).
         """
         self._energy_range = energy_range

biotite/application/blast/webapp.py

@@ -46,7 +46,7 @@ class BlastWebApp(WebApp):
     obey_rules : bool, optional
         If true, the application raises an :class:`RuleViolationError`,
         if the server is contacted too often, based on the NCBI BLAST
-        usage rules. (Default: True)
+        usage rules.
     mail : str, optional
         If a mail address is provided, it will be appended in the
         HTTP request. This allows the NCBI to contact you in case

biotite/application/clustalo/app.py

@@ -172,7 +172,7 @@ class ClustalOmegaApp(MSAApp):
         """
         if self._mbed:
             raise ValueError(
-                "Getting the distance matrix requires " "'full_matrix_calculation()'"
+                "Getting the distance matrix requires 'full_matrix_calculation()'"
             )
         return self._dist_matrix
 

biotite/application/localapp.py

@@ -178,7 +178,7 @@ class LocalApp(Application, metaclass=abc.ABCMeta):
         Returns
         -------
         process : Popen
-            The `Popen` instance
+            The `Popen` instance.
         """
         return self._process
 
@@ -279,7 +279,7 @@ class LocalApp(Application, metaclass=abc.ABCMeta):
         if exit_code != 0:
             err_msg = self.get_stderr().replace("\n", " ")
             raise SubprocessError(
-                f"'{self._bin_path}' returned with exit code {exit_code}: " f"{err_msg}"
+                f"'{self._bin_path}' returned with exit code {exit_code}: {err_msg}"
             )
 
     def clean_up(self):

biotite/application/msaapp.py

@@ -68,7 +68,7 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         # Check matrix symmetry
         if matrix is not None and not matrix.is_symmetric():
             raise ValueError(
-                "A symmetric matrix is required for " "multiple sequence alignments"
+                "A symmetric matrix is required for multiple sequence alignments"
             )
 
         # Check whether the program supports the alignment for the given
@@ -274,12 +274,12 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         Check whether this class supports nucleotide sequences for
         alignment.
 
+        PROTECTED: Override when inheriting.
+
         Returns
         -------
         support : bool
             True, if the class has support, false otherwise.
-
-        PROTECTED: Override when inheriting.
         """
         pass
 
@@ -290,12 +290,12 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         Check whether this class supports nucleotide sequences for
         alignment.
 
+        PROTECTED: Override when inheriting.
+
         Returns
         -------
         support : bool
             True, if the class has support, false otherwise.
-
-        PROTECTED: Override when inheriting.
         """
         pass
 
@@ -306,12 +306,12 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         Check whether this class supports custom substitution matrices
         for protein sequence alignment.
 
+        PROTECTED: Override when inheriting.
+
         Returns
         -------
         support : bool
             True, if the class has support, false otherwise.
-
-        PROTECTED: Override when inheriting.
         """
         pass
 
@@ -322,12 +322,12 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         Check whether this class supports custom substitution matrices
         for nucleotide sequence alignment.
 
+        PROTECTED: Override when inheriting.
+
         Returns
         -------
         support : bool
             True, if the class has support, false otherwise.
-
-        PROTECTED: Override when inheriting.
         """
         pass
 
@@ -342,7 +342,7 @@ class MSAApp(LocalApp, metaclass=abc.ABCMeta):
         Parameters
         ----------
         sequences : iterable object of Sequence
-            The sequences to be aligned
+            The sequences to be aligned.
         bin_path : str, optional
             Path of the MSA software binary. By default, the default
             path will be used.

biotite/application/muscle/app3.py

@@ -29,9 +29,9 @@ class MuscleApp(MSAApp):
     matrix : SubstitutionMatrix, optional
         A custom substitution matrix.
 
-    See also
+    See Also
     --------
-    Muscle5App
+    Muscle5App : Interface to MUSCLE version ``>=5``.
 
     Examples
     --------
@@ -197,7 +197,7 @@ class MuscleApp(MSAApp):
         Parameters
         ----------
         sequences : iterable object of Sequence
-            The sequences to be aligned
+            The sequences to be aligned.
         bin_path : str, optional
             Path of the MSA software binary. By default, the default path
             will be used.

biotite/application/muscle/app5.py

@@ -22,9 +22,9 @@ class Muscle5App(MSAApp):
     bin_path : str, optional
         Path of the MUSCLE binary.
 
-    See also
+    See Also
     --------
-    MuscleApp
+    MuscleApp : Interface to MUSCLE version ``<5``.
 
     Notes
     -----
@@ -147,7 +147,7 @@ class Muscle5App(MSAApp):
         Parameters
         ----------
         sequences : iterable object of Sequence
-            The sequences to be aligned
+            The sequences to be aligned.
         bin_path : str, optional
             Path of the MSA software binary. By default, the default path
             will be used.

biotite/application/sra/app.py

@@ -45,11 +45,6 @@ class _DumpApp(Application, metaclass=abc.ABCMeta):
     prefetch_path, fasterq_dump_path : str, optional
         Path to the ``prefetch_path`` and ``fasterq-dump`` binary,
         respectively.
-    offset : int or {'Sanger', 'Solexa', 'Illumina-1.3', 'Illumina-1.5', 'Illumina-1.8'}, optional
-        This value is subtracted from the FASTQ ASCII code to obtain the
-        quality score.
-        Can either be directly the value, or a string that indicates
-        the score format.
     """
 
     def __init__(

biotite/application/util.py

@@ -17,6 +17,16 @@ def map_sequence(sequence):
     Map a sequence with an arbitrary alphabet into a
     :class:`ProteinSequence`, in order to support arbitrary sequence
     types in software that can handle protein sequences.
+
+    Parameters
+    ----------
+    sequence : Sequence
+        The sequence to be mapped.
+
+    Returns
+    -------
+    mapped_sequence : ProteinSequence
+        The mapped sequence.
     """
     if len(sequence.alphabet) > len(ProteinSequence.alphabet):
         # Cannot map into a protein sequence if the alphabet
@@ -40,10 +50,20 @@ def map_matrix(matrix):
     class:`SubstitutionMatrix` for protein sequences, in order to support
     arbitrary sequence types in software that can handle protein
     sequences.
+
+    Parameters
+    ----------
+    matrix : SubstitutionMatrix
+        The substitution matrix to be mapped.
+
+    Returns
+    -------
+    mapped_matrix : SubstitutionMatrix
+        The mapped substitution matrix.
     """
     if matrix is None:
         raise TypeError(
-            "A substitution matrix must be provided for custom " "sequence types"
+            "A substitution matrix must be provided for custom sequence types"
         )
     # Create a protein substitution matrix with the values taken
     # from the original matrix

biotite/application/viennarna/rnaalifold.py

@@ -167,15 +167,15 @@ class RNAalifoldApp(LocalApp):
         free_energy : float
             The free energy.
 
+        See Also
+        --------
+        get_covariance_energy : Get the energy of the artificial covariance term.
+
         Notes
         -----
         The total energy of the secondary structure regarding the
         minimization objective is the sum of the free energy and the
         covariance term.
-
-        See also
-        --------
-        get_covariance_energy
         """
         return self._free_energy
 
@@ -190,15 +190,15 @@ class RNAalifoldApp(LocalApp):
         covariance_energy : float
             The energy of the covariance term.
 
+        See Also
+        --------
+        get_free_energy : Get the free energy.
+
         Notes
         -----
         The total energy of the secondary structure regarding the
         minimization objective is the sum of the free energy and the
         covariance term.
-
-        See also
-        --------
-        get_free_energy
         """
         return self._covariance_energy
 

biotite/application/viennarna/rnaplot.py

@@ -28,15 +28,15 @@ class RNAplotApp(LocalApp):
 
     Parameters
     ----------
-    dot_bracket : str, optional (default: None)
+    dot_bracket : str, optional
         The structure in dot bracket notation.
-    base_pairs : ndarray, shape=(n,2), optional (default: None)
+    base_pairs : ndarray, shape=(n,2), optional
         Each row corresponds to the positions of the bases in the
         strand. This parameter is mutually exclusive to ``dot_bracket``.
-    length : int, optional (default: None)
+    length : int, optional
         The number of bases in the strand. This parameter is required if
         ``base_pairs`` is given.
-    layout_type : RNAplotApp.Layout, optional (default: RNAplotApp.Layout.NAVIEW)
+    layout_type : RNAplotApp.Layout, optional
         The layout type according to the *RNAplot* documentation.
     bin_path : str, optional
         Path of the *RNAplot* binary.
@@ -124,7 +124,7 @@ class RNAplotApp(LocalApp):
 
         Parameters
         ----------
-        type : RNAplotApp.Layout
+        layout_type : RNAplotApp.Layout
             The layout type.
         """
         self._layout_type = str(layout_type)
@@ -176,15 +176,17 @@ class RNAplotApp(LocalApp):
 
         Parameters
         ----------
-        dot_bracket : str, optional (default: None)
+        dot_bracket : str, optional
             The structure in dot bracket notation.
-        base_pairs : ndarray, shape=(n,2), optional (default: None)
+        base_pairs : ndarray, shape=(n,2), optional
             Each row corresponds to the positions of the bases in the
             strand. This parameter is mutually exclusive to
             ``dot_bracket``.
-        length : int, optional (default: None)
+        length : int, optional
             The number of bases in the strand. This parameter is
             required if ``base_pairs`` is given.
+        layout_type : Layout
+            The desired layout of the plot.
         bin_path : str, optional
             Path of the *RNAplot* binary.
 

biotite/application/viennarna/util.py

@@ -39,7 +39,7 @@ def build_constraint_string(
     Returns
     -------
     constraints : str
-        The constraint string
+        The constraint string.
     """
     constraints = np.full(sequence_length, ".", dtype="U1")
 

biotite/application/webapp.py

@@ -29,7 +29,7 @@ class WebApp(Application, metaclass=abc.ABCMeta):
         URL of the web app.
     obey_rules : bool, optional
         If true, the application raises an :class:`RuleViolationError`, if
-        the server rules are violated. (Default: True)
+        the server rules are violated.
     """
 
     def __init__(self, app_url, obey_rules=True):

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,191 @@
+# 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
+_UNIPROT_PATTERN = (
+    "[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2}"
+)
+
+
+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``) or AlphaFold DB IDs
+        (e.g. ``AF-P12345F1``).
+    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)
+    metadata = requests.get(f"{_METADATA_URL}/{uniprot_id}").json()
+    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.search(_UNIPROT_PATTERN, id)
+    if match is None:
+        raise ValueError(f"Cannot extract AFDB identifier from '{id}'")
+    return match.group()
+
+
+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/dbnames.py

@@ -80,6 +80,16 @@ def sanitize_database_name(db_name):
     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

biotite/database/entrez/download.py

@@ -54,17 +54,16 @@ def fetch(
     db_name : str:
         E-utility or common database name.
     ret_type : str
-        Retrieval type
+        Retrieval type.
     ret_mode : str, optional
-        Retrieval mode
+        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. (Default: False)
-    verbose: bool, optional
+        empty.
+    verbose : bool, optional
         If true, the function will output the download progress.
-        (Default: False)
 
     Returns
     -------
@@ -84,9 +83,9 @@ def fetch(
     When the issue occurs repeatedly, the error is probably in your
     input.
 
-    See also
+    See Also
     --------
-    fetch_single_file
+    fetch_single_file : Fetch multiple entries as a single file.
 
     Examples
     --------
@@ -111,7 +110,7 @@ def fetch(
     for i, id in enumerate(uids):
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(uids):d} ({id})...", end="\r")
+            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)
@@ -188,9 +187,9 @@ def fetch_single_file(
     When the issue occurs repeatedly, the error is probably in your
     input.
 
-    See also
+    See Also
     --------
-    fetch
+    fetch : Fetch one or multiple entries as separate files.
     """
     if (
         file_name is not None

biotite/database/entrez/key.py

@@ -37,7 +37,7 @@ def set_api_key(key):
 
     Parameters
     ----------
-    api_key : str
+    key : str
         The API key.
     """
     global _API_KEY

biotite/database/entrez/query.py

@@ -60,9 +60,9 @@ class CompositeQuery(Query):
 
     Parameters
     ----------
-    operator: str, {"AND", "OR", "NOT"}
+    operator : str, {"AND", "OR", "NOT"}
         The combination operator.
-    queries : iterable object of SimpleQuery
+    query1, query2 : SimpleQuery
         The queries to be combined.
 
     Examples
@@ -97,7 +97,7 @@ class SimpleQuery(Query):
 
     Parameters
     ----------
-    term: str
+    term : str
         The search term.
     field : str, optional
         The field to search the term in.
@@ -173,7 +173,8 @@ class SimpleQuery(Query):
         "SUBS",
         "WORD",
         "TI",
-        "TITL" "VOL",
+        "TITL",
+        "VOL",
     ]
 
     def __init__(self, term, field=None):