Implementation of fetch_pdb() (#4943)

  ENH: Add MDAnalysis.fetch module for downloading PDB structures from RCSB

  Adds a new `MDAnalysis.fetch` subpackage providing `from_PDB()`, which
  downloads one or more PDB structure files from the RCSB wwPDB server via
  `pooch`-managed caching. Returns `pathlib.Path` objects suitable for
  direct use with `mda.Universe()`.

  - `from_PDB(pdb_ids, cache_path, file_format, progressbar)` supports all
    RCSB-provided formats (cif, pdb, bcif, xml and their .gz variants)
  - Caches files under `pooch.os_cache("MDAnalysis_pdbs")` by default;
    re-downloads are skipped for cached files
  - Raises `ModuleNotFoundError` when pooch is absent, `ValueError` on
    unsupported format, and propagates `requests.HTTPError` for bad PDB IDs
  - `pooch` added to the `extra_formats` optional dependency group in
    `pyproject.toml`

Fixes #4907

---------

Co-authored-by: Oliver Beckstein <orbeckst@gmail.com>
Co-authored-by: Brady Johnston <36021261+BradyAJohnston@users.noreply.github.com>

Author: 3 people

.github/actions/setup-deps/action.yaml

@@ -74,6 +74,8 @@ inputs:
     default: 'networkx'
   openmm:
     default: 'openmm'
+  pooch:
+    default: 'pooch'
   pytng:
     default: 'pytng>=0.2.3'
   rdkit:
@@ -145,6 +147,7 @@ runs:
           ${{ inputs.netcdf4 }}
           ${{ inputs.networkx }}
           ${{ inputs.openmm }}
+          ${{ inputs.pooch }}
           ${{ inputs.pytng }}
           ${{ inputs.rdkit }}
           ${{ inputs.scikit-learn }}

package/CHANGELOG

@@ -16,7 +16,7 @@ The rules for this file:
 -------------------------------------------------------------------------------
 ??/??/?? IAlibay, orbeckst, marinegor, tylerjereddy, ljwoods2, marinegor,
          spyke7, talagayev, tanii1125, BradyAJohnston, hejamu, jeremyleung521,
-         harshitgajjela-droid, kunjsinha, aygarwal
+         harshitgajjela-droid, kunjsinha, aygarwal, jauy123
 
  * 2.11.0
 
@@ -42,6 +42,9 @@ Fixes
    DSSP by porting upstream PyDSSP 0.9.1 fix (Issue #4913)
 
 Enhancements
+ * Added new top-level `MDAnalysis.fetch` module (PR #4943)
+ * Added new function `MDAnalysis.fetch.from_PDB` to download structure files from wwPDB
+   using `pooch` as optional dependency (Issue #4907, PR #4943) 
  * Added benchmarks for package.MDAnalysis.analysis.msd.EinsteinMSD (PR #5277)
  * Improved performance of `AtomGroup.wrap()` with compounds (PR #5220)
  * Adds support for parsing `.tpr` files produced by GROMACS 2026.0

package/MDAnalysis/fetch/__init__.py

@@ -0,0 +1,39 @@
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the Lesser GNU Public Licence, v2.1 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+# doi: 10.25080/majora-629e541a-00e
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+
+"""
+Web Retrieval Services --- :mod:`MDAnalysis.fetch`
+==================================================
+
+The :mod:`MDAnalysis.fetch` module contains various functions that are able to download
+resources from the internet. All functions return a :class:`~pathlib.Path` object.
+:class:`~pathlib.Path` objects are able to be passed as argument to initalize an
+instance of :class:`~MDAnalysis.core.universe.Universe`.
+
+To use these functions, the optional dependency :mod:`pooch` is required.
+
+"""
+
+__all__ = ["from_PDB"]
+
+from .pdb import from_PDB

package/MDAnalysis/fetch/pdb.py

@@ -0,0 +1,200 @@
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding: utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the Lesser GNU Public Licence, v2.1 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+# doi: 10.25080/majora-629e541a-00e
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+
+"""
+PDB Fetchers --- :mod:`MDAnalysis.fetch.pdb`
+============================================
+
+This suite of functions download structure files from the Research Collaboratory for
+Structural Bioinformatics (RCSB) `Protein Data Batabank`_ (PDB).
+
+.. _Protein Data Batabank: https://www.rcsb.org/
+
+Variables
+---------
+
+.. autodata:: DEFAULT_CACHE_NAME_DOWNLOADER
+
+
+Functions
+---------
+
+.. autofunction:: from_PDB
+
+"""
+from pathlib import Path
+
+try:
+    import pooch
+except ImportError:
+    HAS_POOCH = False
+else:
+    HAS_POOCH = True
+
+#: Name of the :mod:`pooch` cache directory ``pooch.os_cache(DEFAULT_CACHE_NAME_DOWNLOADER)``;
+#: see :func:`pooch.os_cache` for further details.
+#:
+#: .. versionadded:: 2.11.0
+DEFAULT_CACHE_NAME_DOWNLOADER = "MDAnalysis_pdbs"
+
+# These file formats are here https://www.rcsb.org/docs/programmatic-access/file-download-services#pdb-entry-files"
+SUPPORTED_FILE_FORMATS_DOWNLOADER = (
+    "cif",
+    "cif.gz",
+    "bcif",
+    "bcif.gz",
+    "xml",
+    "xml.gz",
+    "pdb",
+    "pdb.gz",
+    "pdb1",
+    "pdb1.gz",
+)
+
+
+def from_PDB(
+    pdb_ids,
+    cache_path=None,
+    progressbar=False,
+    file_format="cif.gz",
+):
+    """
+    Download one or more PDB files from the RCSB Protein Data Bank and cache
+    them locally.
+
+    Given one or multiple PDB IDs, downloads the corresponding structure files
+    format and stores them in a local cache directory. If files are cached on
+    disk, *from_PDB* will skip the download and use the cached version instead.
+
+    Returns the path(s) as a :class:`~pathlib.Path` to the downloaded file(s).
+
+    Parameters
+    ----------
+    pdb_ids : str or sequence of str
+        A single PDB ID as a string, or a sequence of PDB IDs to fetch.
+    cache_path : str or pathlib.Path
+        Directory where downloaded file(s) will be cached.
+        The default ``None`` argument uses the :mod:`pooch` default cache with
+        project name :data:`DEFAULT_CACHE_NAME_DOWNLOADER`.
+    file_format : str
+        The file extension/format to download (e.g., "cif", "pdb").
+        See the Notes section below for a list of all supported file formats.
+    progressbar : bool
+        If True, display a progress bar during file downloads. Default is False.
+
+    Returns
+    -------
+    :class:`~pathlib.Path` or list of :class:`~pathlib.Path`
+        The path(s) to the downloaded file(s). Returns a single
+        :class:`~pathlib.Path` if a single pdb id is given, or a list of
+        :class:`~pathlib.Path` if multiple pdb ids are provided.
+
+    Raises
+    ------
+    ValueError
+        For an invalid file format. Supported file formats are under Notes.
+
+    :class:`requests.exceptions.HTTPError`
+        If an invalid PDB code is specified.
+
+    Notes
+    -----
+    This function uses the `RCSB File Download Services`_ for directly downloading
+    structure files via https.
+
+    .. _`RCSB File Download Services`:
+       https://www.rcsb.org/docs/programmatic-access/file-download-services
+
+    The RCSB currently provides data in ``'cif'`` , ``'cif.gz'`` , ``'bcif'`` ,
+    ``'bcif.gz'`` , ``'xml'`` , ``'xml.gz'`` , ``'pdb'`` , ``'pdb.gz'``,
+    ``'pdb1'``, ``'pdb1.gz'`` file formats and can therefore be downloaded.
+    Not all of these formats can be currently read with MDAnalysis.
+
+    Caching, controlled by the `cache_path` parameter, is handled internally by
+    :mod:`pooch`. The default cache name is taken from
+    :data:`DEFAULT_CACHE_NAME_DOWNLOADER`. To clear cache (and subsequently force
+    re-fetching), it is required to delete the cache folder as specified by
+    `cache_path`.
+
+    Examples
+    --------
+    Download a single PDB file:
+
+    >>> mda.fetch.from_PDB("1AKE", file_format="cif")
+    './MDAnalysis_pdbs/1AKE.cif'
+
+    Download multiple PDB files with a progress bar:
+
+    >>> mda.fetch.from_PDB(["1AKE", "4BWZ"], progressbar=True)
+    ['./MDAnalysis_pdbs/1AKE.pdb.gz', './MDAnalysis_pdbs/4BWZ.pdb.gz']
+
+    Download a single PDB file and convert it to a universe:
+
+    >>> mda.Universe(mda.fetch.from_PDB("1AKE"), file_format="pdb.gz")
+    <Universe with 3816 atoms>
+
+    Download multiple PDB files and convert each of them into a universe:
+
+    >>> [mda.Universe(pdb) for pdb in mda.fetch.from_PDB(["1AKE", "4BWZ"], progressbar=True)]
+    [<Universe with 3816 atoms>, <Universe with 2824 atoms>]
+
+
+    .. versionadded:: 2.11.0
+    """
+
+    if not HAS_POOCH:
+        raise ModuleNotFoundError(
+            "pooch is needed as a dependency for from_PDB()"
+        )
+    elif file_format not in SUPPORTED_FILE_FORMATS_DOWNLOADER:
+        raise ValueError(
+            "Invalid file format. Supported file formats "
+            f"are {SUPPORTED_FILE_FORMATS_DOWNLOADER}"
+        )
+
+    if isinstance(pdb_ids, str):
+        _pdb_ids = (pdb_ids,)
+    else:
+        _pdb_ids = pdb_ids
+
+    if cache_path is None:
+        cache_path = pooch.os_cache(DEFAULT_CACHE_NAME_DOWNLOADER)
+
+    # Have to do this dictionary approach instead of using pooch.retrieve in order
+    # to prevent the hardcoded known_hash warning from showing up.
+    registry_dictionary = {
+        f"{pdb_id}.{file_format}": None for pdb_id in _pdb_ids
+    }
+
+    downloader = pooch.create(
+        path=cache_path,
+        base_url="https://files.wwpdb.org/download/",
+        registry=registry_dictionary,
+    )
+
+    paths = [
+        Path(downloader.fetch(fname=file_name, progressbar=progressbar))
+        for file_name in registry_dictionary.keys()
+    ]
+
+    return paths if not isinstance(pdb_ids, str) else paths[0]

package/doc/sphinx/source/conf.py

@@ -350,4 +350,6 @@ class KeyStyle(UnsrtStyle):
     "mdahole2": ("https://www.mdanalysis.org/mdahole2/", None),
     "dask": ("https://docs.dask.org/en/stable/", None),
     "imdclient": ("https://imdclient.readthedocs.io/en/stable/", None),
+    "pooch": ("https://www.fatiando.org/pooch/latest/", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
 }

package/doc/sphinx/source/documentation_pages/fetchers/PDB.rst

@@ -0,0 +1 @@
+.. automodule:: MDAnalysis.fetch.pdb

package/doc/sphinx/source/documentation_pages/fetchers/init.rst

@@ -0,0 +1 @@
+.. automodule:: MDAnalysis.fetch.__init__

package/doc/sphinx/source/documentation_pages/fetchers_modules.rst

@@ -0,0 +1,18 @@
+.. Contains the formatted docstrings from the fetch modules located in 'mdanalysis/MDAnalysis/fetch'
+
+**************************
+Fetchers modules
+**************************
+
+The fetch module contains code that are able to retrieve data from
+the internet. All code in this module currently depends on the 
+dependency :mod:`pooch` which is required in order to run this
+module. 
+
+.. rubric:: Fetcher functions
+
+.. toctree::
+   :maxdepth: 1
+
+   fetchers/init
+   fetchers/PDB

package/doc/sphinx/source/index.rst

@@ -125,6 +125,7 @@ Thank you!
    ./documentation_pages/guesser_modules
    ./documentation_pages/coordinates_modules
    ./documentation_pages/converters
+   ./documentation_pages/fetchers_modules
    ./documentation_pages/trajectory_transformations
    ./documentation_pages/selections_modules
    ./documentation_pages/auxiliary_modules

package/pyproject.toml

@@ -72,6 +72,7 @@ extra_formats = [
     "h5py>=2.10",
     "chemfiles>=0.10",
     "parmed",
+    "pooch",
     "pyedr>=0.7.0",
     "pytng>=0.2.3",
     "gsd>3.0.0",