Source code for MDAnalysis.fetch.pdb
# -*- 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
.. autofunction:: from_ALPHAFOLD
"""
import json
from urllib.request import urlretrieve
from tempfile import TemporaryDirectory
from .fetchers import StaticFetcher
#: Alias to fetchers/DEFAULT_CACHE_NAME_DOWNLOADER
#:
#: Maintained for backwards compatiblity
#:
from .fetchers import DEFAULT_CACHE_NAME_DOWNLOADER
# These file formats are here https://www.rcsb.org/docs/programmatic-access/file-download-services#pdb-entry-files"
_SUPPORTED_FILE_FORMATS_PDB = (
"cif",
"cif.gz",
"bcif",
"bcif.gz",
"xml",
"xml.gz",
"pdb",
"pdb.gz",
"pdb1",
"pdb1.gz",
)
# These file formats are fields in the alphafold API
# https://alphafold.ebi.ac.uk/api-docs
_SUPPORTED_FILE_FORMATS_ALPHAFOLD = {
"bcif": "bcifUrl",
"cif": "cifUrl",
"pdb": "pdbUrl",
}
[docs]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 file_format not in _SUPPORTED_FILE_FORMATS_PDB:
raise ValueError(
"Invalid file format. Supported file formats "
f"are {_SUPPORTED_FILE_FORMATS_PDB}"
)
if isinstance(pdb_ids, str):
_pdb_ids = (pdb_ids + "." + file_format,)
else:
_pdb_ids = [pdb + "." + file_format for pdb in pdb_ids]
fetcher = StaticFetcher(cache_path=cache_path)
return fetcher.fetch(
file_name=_pdb_ids,
base_url="https://files.wwpdb.org/download/",
progressbar=progressbar,
append_db=True,
)
[docs]def from_ALPHAFOLD(id, cache_path=None, progressbar=False, file_format="cif"):
"""
Download one or more AlphaFold structure files and cache them locally.
Given one AlphaFold ID, downloads the corresponding structure file in the
specified format and stores it in a local cache directory. If files are
cached on disk, *from_ALPHAFOLD* 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
----------
id : str
A single AlphaFold ID as a string.
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` for the downloaded AlphaFold file.
Raises
------
ValueError
For an invalid file format. Supported file formats are under Notes.
:class:`requests.exceptions.HTTPError`
If an invalid AlphaFold ID is specified.
Notes
-----
This function uses the `AlphaFold API`_ for directly
downloading structure files via HTTP GET.
.. _`AlphaFold API`:
https://alphafold.ebi.ac.uk/api-docs
AlphaFold currently provides data in ``'cif'``, ``'pdb'``, and ``'bcif'``
file formats and can therefore be downloaded. Not all of these
formats can be currently read with MDAnalysis.
At the current moment, this function only supports
downloading a single AlphaFold ID at a time unlike in :func:`from_PDB`
which can download multiple PDB IDs at once.
Additionally, there is currently no support for downloading prior
versions of AlphaFold predictions. The `AlphaFold API`_
only provides the latest version of the prediction for
a given ID. For more detailed control, it is recommended to browse
`AlphaFold <https://alphafold.ebi.ac.uk/>`_ manually.
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 AlphaFold file:
>>> from_ALPHAFOLD("Q9I1F6", file_format="cif")
'./MDAnalysis_pdbs/AF-Q9I1F6-F1-model_v6.cif'
Download a single AlphaFold file and convert it to a universe:
>>> mda.Universe(from_ALPHAFOLD("Q9I1F6"), files_format="pdb")
<Universe with 2608 atoms>
.. versionadded:: 2.11.0
"""
if file_format not in _SUPPORTED_FILE_FORMATS_ALPHAFOLD.keys():
raise ValueError(
f"Invalid file format: {file_format}. "
+ "Supported formats are: "
+ f"{list(_SUPPORTED_FILE_FORMATS_ALPHAFOLD.keys())}"
)
# Save JSON file to temporary directory.
# This also prevents StaticFetcher logging from occuring in the console
with TemporaryDirectory() as tmp_dir_path:
json_file, _ = urlretrieve(
f"https://alphafold.ebi.ac.uk/api/prediction/{id}",
f"{tmp_dir_path}/{id}.json",
)
with open(json_file) as _json:
data = json.load(_json)[0]
url = data[_SUPPORTED_FILE_FORMATS_ALPHAFOLD[file_format]]
# This splits urls such as
# https://alphafold.ebi.ac.uk/files/AF-Q9I1F6-F1-model_v6.cif into
# https://alphafold.ebi.ac.uk/files and AF-Q9I1F6-F1-model_v6.cif
base_url, file = url.rsplit("/", 1)
fetcher = StaticFetcher(cache_path=cache_path)
return fetcher.fetch(
base_url=base_url,
file_name=file,
progressbar=progressbar,
append_db=True,
)