Bio.Entrez 包

子模块

• Bio.Entrez.Parser 模块
  • NoneElement
    • NoneElement.__init__()
    • NoneElement.__eq__()
    • NoneElement.__ne__()
    • NoneElement.__repr__()
    • NoneElement.__hash__
  • IntegerElement
    • IntegerElement.__new__()
    • IntegerElement.__init__()
    • IntegerElement.__repr__()
  • StringElement
    • StringElement.__new__()
    • StringElement.__init__()
    • StringElement.__repr__()
  • ListElement
    • ListElement.__init__()
    • ListElement.__repr__()
    • ListElement.store()
  • DictionaryElement
    • DictionaryElement.__init__()
    • DictionaryElement.__repr__()
    • DictionaryElement.store()
  • OrderedListElement
    • OrderedListElement.__init__()
    • OrderedListElement.__repr__()
    • OrderedListElement.store()
  • ErrorElement
    • ErrorElement.__new__()
    • ErrorElement.__init__()
    • ErrorElement.__repr__()
  • NotXMLError
    • NotXMLError.__init__()
    • NotXMLError.__str__()
  • CorruptedXMLError
    • CorruptedXMLError.__init__()
    • CorruptedXMLError.__str__()
  • ValidationError
    • ValidationError.__init__()
    • ValidationError.__str__()
  • DataHandlerMeta
    • DataHandlerMeta.__init__()
    • DataHandlerMeta.directory
  • DataHandler
    • DataHandler.global_dtd_dir
    • DataHandler.global_xsd_dir
    • DataHandler.local_dtd_dir
    • DataHandler.local_xsd_dir
    • DataHandler.__init__()
    • DataHandler.read()
    • DataHandler.parse()
    • DataHandler.xmlDeclHandler()
    • DataHandler.handleMissingDocumentDefinition()
    • DataHandler.startNamespaceDeclHandler()
    • DataHandler.endNamespaceDeclHandler()
    • DataHandler.schemaHandler()
    • DataHandler.startElementHandler()
    • DataHandler.startRawElementHandler()
    • DataHandler.startSkipElementHandler()
    • DataHandler.endStringElementHandler()
    • DataHandler.endRawElementHandler()
    • DataHandler.endSkipElementHandler()
    • DataHandler.endErrorElementHandler()
    • DataHandler.endElementHandler()
    • DataHandler.endIntegerElementHandler()
    • DataHandler.characterDataHandlerRaw()
    • DataHandler.characterDataHandlerEscape()
    • DataHandler.skipCharacterDataHandler()
    • DataHandler.parse_xsd()
    • DataHandler.elementDecl()
    • DataHandler.open_dtd_file()
    • DataHandler.open_xsd_file()
    • DataHandler.save_dtd_file()
    • DataHandler.save_xsd_file()
    • DataHandler.externalEntityRefHandler()

模块内容

提供用于通过 WWW 访问 NCBI 的代码。

Entrez 主页位于：http://www.ncbi.nlm.nih.gov/Entrez/

Entrez 编程工具主页位于：http://www.ncbi.nlm.nih.gov/books/NBK25501/

此模块提供许多功能，例如 efetch（Entrez Fetch 的缩写），它将以句柄对象的形式返回数据。这是一种用于在 Python 中从文件（在本例中为远程网络连接）读取数据的标准接口，并提供诸如 .read() 之类的函数，或者允许逐行迭代内容。请参阅 Biopython 教程和食谱中的“句柄到底是什么？”：https://biopython.pythonlang.cn/DIST/docs/tutorial/Tutorial.html https://biopython.pythonlang.cn/DIST/docs/tutorial/Tutorial.pdf 这些函数返回的句柄可以是文本模式或二进制模式，具体取决于请求的数据和 NCBI Entrez 返回的结果。通常，XML 数据将以二进制模式存在，而其他数据将以文本模式存在，这是后续解析器解析数据所需的。

与来自 open(filename) 函数的磁盘上文件的句柄不同，后者具有一个 .name 属性，用于提供文件名，来自 Bio.Entrez 的句柄都具有一个 .url 属性，用于提供用于连接到 NCBI Entrez API 的 URL。

epost，efetch 和 esummary 工具使用“id”参数，该参数对应于一个或多个数据库 UID（或在“nuccore”或“protein”等序列数据库的情况下，对应于 accession.version 标识符）。传递给这些函数的“id”关键字的 Python 值可以是单个 ID（作为字符串或整数），也可以是多个 ID（作为字符串/整数的迭代器）。您也可以传递包含多个 ID 的单个字符串，这些 ID 由逗号分隔。 elink 工具也接受多个 ID，但参数的处理方式与其他三个工具不同。有关更多信息，请参阅该函数的文档字符串。

所有向 NCBI Entrez API 发送请求的函数都将自动遵守 NCBI 速率限制（在没有 API 密钥的情况下，每秒 3 个请求，或者在有 API 密钥的情况下，每秒 10 个请求），并且在遇到瞬时错误（例如连接错误或 HTTP 5XX 代码）时会自动重试。默认情况下，Biopython 在放弃之前最多尝试三次，并在每次尝试之间休眠 15 秒。可以通过设置 Bio.Entrez.max_tries 和 Bio.Entrez.sleep_between_tries 来调整这些参数。

Entrez 模块还提供一个 XML 解析器，该解析器以句柄作为输入。

变量

• email 设置 Entrez 电子邮件参数（默认情况下未设置）。

• tool 设置 Entrez 工具参数（默认值为 biopython）。

• api_key 来自 NCBI 的个人 API 密钥。如果未设置，则每秒仅允许 3 个查询。使用有效的 API 密钥，每秒 10 个查询。

• max_tries 配置在遇到错误时自动重试失败请求的次数（默认值为 3）。

• sleep_between_tries 在遇到错误时，重试请求之前的延迟时间（以秒为单位）（默认值为 15）。

函数

• efetch 从一个或多个主 ID 列表或从用户的环境中检索以请求格式提供的记录

• epost 将包含主 ID 列表的文件发布到用户的环境中，以供在后续搜索策略中使用

• esearch 搜索并检索主 ID（用于 EFetch、ELink 和 ESummary），以及术语翻译，并可以选择保留结果以供将来在用户的环境中使用。

• elink 检查从一个或多个主 ID 列表中是否存在外部链接或相关文章链接。检索指向 Entrez 数据库或相关文章的链接的主 ID 和相关性分数；为特定 ID 和数据库创建指向主要 LinkOut 提供者的超链接，或者列出多个 ID 的 LinkOut URL 和属性。

• einfo 为每个数据库提供字段索引术语计数、最后更新时间和可用链接。

• esummary 从一个或多个主 ID 列表或从用户的环境中检索文档摘要。

• egquery 为使用全局查询的单个搜索提供 XML 格式的 Entrez 数据库计数。

• espell 检索拼写建议。

• ecitmatch 检索与一组输入引文字符串相对应的 PubMed ID（PMID）。

• read 解析由上述任何函数返回的 XML 结果。或者，可以从以二进制模式打开的文件中读取 XML 数据。典型用法是

  >>> from Bio import Entrez
  >>> Entrez.email = "[email protected]"
  >>> handle = Entrez.einfo() # or esearch, efetch, ...
  >>> record = Entrez.read(handle)
  >>> handle.close()
  

  其中 record 现在是一个 Python 字典或列表。

• parse 解析由上述可以返回多个记录的函数（如 efetch、esummary 和 elink）返回的 XML 结果。典型用法是

  >>> handle = Entrez.esummary(db="pubmed", id="19304878,14630660", retmode="xml")
  >>> records = Entrez.parse(handle)
  >>> for record in records:
  ...     # each record is a Python dictionary or list.
  ...     print(record['Title'])
  Biopython: freely available Python tools for computational molecular biology and bioinformatics.
  PDB file parser and structure class implemented in Python.
  >>> handle.close()
  

  此函数仅适用于 XML 文件包含多个记录的情况，对于大型文件特别有用。

• _open 内部使用的函数。

Bio.Entrez.epost(db, **keywds)

发布一个标识符文件以供将来使用。

将包含 UI 列表的文件发布到用户的环境中，以供在后续搜索策略中使用。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EPost

返回:

指向结果的句柄。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.efetch(db, **keywords)

获取以句柄形式返回的 Entrez 结果。

EFetch 从一个或多个 UI 列表或从用户的环境中检索以请求格式提供的记录。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EFetch

简短示例

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> handle = Entrez.efetch(db="nucleotide", id="AY851612", rettype="gb", retmode="text")
>>> print(handle.readline().strip())
LOCUS       AY851612                 892 bp    DNA     linear   PLN 10-APR-2007
>>> handle.close()

如果标识符超过 200 个，这将自动使用 HTTP POST 而不是 HTTP GET，这是 NCBI 建议的。

警告： NCBI 在 2012 年 2 月更改了默认的 retmode，因此许多以前返回文本输出的数据库现在都返回 XML。

返回:

指向结果的句柄。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.esearch(db, term, **keywds)

运行 Entrez 搜索并返回结果句柄。

ESearch 搜索并检索主 ID（用于 EFetch、ELink 和 ESummary），以及术语翻译，并可以选择保留结果以供用户环境将来使用。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESearch

简短示例

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> handle = Entrez.esearch(
...     db="nucleotide", retmax=10, idtype="acc",
...     term="opuntia[ORGN] accD 2007[Publication Date]"
... )
...
>>> record = Entrez.read(handle)
>>> handle.close()
>>> int(record["Count"]) >= 2
True
>>> "EF590893.1" in record["IdList"]
True
>>> "EF590892.1" in record["IdList"]
True

返回:

结果句柄，始终为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.elink(**keywds)

检查链接的外部文章并返回句柄。

ELink 检查从一个或多个主 ID 列表中是否存在外部或相关文章链接；检索到 Entrez 数据库或相关文章的链接的 ID 和相关性得分；为特定 ID 和数据库创建指向主要 LinkOut 提供者的超链接，或者列出多个 ID 的 LinkOut URL 和属性。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ELink

请注意，当给出多个值时，ELink 对“id”参数的处理方式与其他工具不同。通常应将多个 UID 作为字符串或整数列表传递。这将在结果中提供从源数据库 UID 到目标数据库 UID 的“一对一”映射。如果将多个源 UID 作为单个逗号分隔的字符串传递，则所有目标 UID 将在结果中混合在一起。

此示例查找与 Biopython 应用说明在 PubMed 数据库中的条目相关的文章

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> pmid = "19304878"
>>> handle = Entrez.elink(dbfrom="pubmed", id=pmid, linkname="pubmed_pubmed")
>>> record = Entrez.read(handle)
>>> handle.close()
>>> print(record[0]["LinkSetDb"][0]["LinkName"])
pubmed_pubmed
>>> linked = [link["Id"] for link in record[0]["LinkSetDb"][0]["Link"]]
>>> "14630660" in linked
True

在 Biopython 教程中对这一点进行了更详细的解释。

返回:

结果句柄，默认情况下为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.einfo(**keywds)

返回 Entrez 数据库摘要作为结果句柄。

EInfo 提供每个 Entrez 数据库的字段名称、索引词计数、上次更新和可用链接。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EInfo

简短示例

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> record = Entrez.read(Entrez.einfo())
>>> 'pubmed' in record['DbList']
True

返回:

结果句柄，默认情况下为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.esummary(**keywds)

检索文档摘要作为结果句柄。

ESummary 从主 ID 列表或用户环境中检索文档摘要。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESummary

此示例发现有关结构数据库中的条目 19923 的更多信息

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> handle = Entrez.esummary(db="structure", id="19923")
>>> record = Entrez.read(handle)
>>> handle.close()
>>> print(record[0]["Id"])
19923
>>> print(record[0]["PdbDescr"])
CRYSTAL STRUCTURE OF E. COLI ACONITASE B

返回:

结果句柄，默认情况下为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.egquery(**keywds)

为全局搜索提供 Entrez 数据库计数（已弃用）。

EGQuery 使用全局查询为单个搜索提供 Entrez 数据库计数的 XML。但是，NCBI 不再维护此功能，建议对每个感兴趣的数据库使用 esearch。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EGQuery

此来自 Biopython 教程的较长版本的快速示例仅检查 PubMedCentral 中“Biopython”的匹配项是否超过 60 个

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> handle = Entrez.egquery(term="biopython")  
>>> record = Entrez.read(handle)  
>>> handle.close()  
>>> for row in record["eGQueryResult"]:  
...     if "pmc" in row["DbName"]:  
...         print(int(row["Count"]) > 60)  
True

返回:

结果句柄，默认情况下为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.espell(**keywds)

检索拼写建议作为结果句柄。

ESpell 检索拼写建议（如果可用）。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESpell

简短示例

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> record = Entrez.read(Entrez.espell(term="biopythooon"))
>>> print(record["Query"])
biopythooon
>>> print(record["CorrectedQuery"])
biopython

返回:

结果句柄，默认情况下为 XML 格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.ecitmatch(**keywds)

检索输入引文字符串的 PMID，作为句柄返回。

ECitMatch 检索与一组输入引文字符串相对应的 PubMed ID（PMID）。

有关参数的说明，请参阅在线文档：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ECitMatch

简短示例

>>> from Bio import Entrez
>>> Entrez.email = "[email protected]"
>>> citation_1 = {"journal_title": "proc natl acad sci u s a",
...               "year": "1991", "volume": "88", "first_page": "3248",
...               "author_name": "mann bj", "key": "citation_1"}
>>> handle = Entrez.ecitmatch(db="pubmed", bdata=[citation_1])
>>> print(handle.read().strip().split("|"))
['proc natl acad sci u s a', '1991', '88', '3248', 'mann bj', 'citation_1', '2014248']
>>> handle.close()

返回:

结果句柄，默认情况下为纯文本格式。

引发:

urllib.error.URLError – 如果出现网络错误。

Bio.Entrez.read(source, validate=True, escape=False, ignore_errors=False)

将来自 NCBI Entrez 实用程序的 XML 文件解析为 python 对象。

此函数解析由 NCBI 的 Entrez 实用程序创建的 XML 文件，返回 Python 列表和字典的多级数据结构。NCBI 的 Entrez 实用程序返回的大多数 XML 文件都可以通过此函数解析，前提是其 DTD 可用。Biopython 包含大多数常用 Entrez 实用程序的 DTD。

参数source必须是以二进制模式打开的文件或类文件对象，或文件名。解析器从 XML 文件中检测编码，并使用它将 XML 中的所有文本转换为正确的 Unicode 字符串。Bio.Entrez 中访问 NCBI Entrez 的函数将自动以二进制模式返回 XML 数据。对于文件，在打开文件时使用模式“rb”，如

>>> from Bio import Entrez
>>> path = "Entrez/esearch1.xml"
>>> stream = open(path, "rb")  # opened in binary mode
>>> record = Entrez.read(stream)
>>> print(record['QueryTranslation'])
biopython[All Fields]
>>> stream.close()

或者，您可以直接使用文件名，如

>>> record = Entrez.read(path)
>>> print(record['QueryTranslation'])
biopython[All Fields]

这更安全，因为文件流将在记录读取完毕后或发生错误时自动关闭。

如果 validate 为 True（默认值），解析器将根据 DTD 验证 XML 文件，如果 XML 文件包含 DTD 中没有表示的标签，则会引发错误。如果 validate 为 False，解析器将简单地跳过这些标签。

如果 escape 为 True，则所有非法的 HTML 字符都将被替换为 HTML 转义字符，以确保返回的字符串是有效的 HTML 片段。例如，小于号（<）将被替换为 &lt;。如果 escape 为 False（默认值），则字符串将按原样返回。

如果 ignore_errors 为 False（默认值），则 XML 文件中的任何错误消息都将引发 RuntimeError。如果 ignore_errors 为 True，则错误消息将被存储为 ErrorElement 项，而不会引发异常。

虽然数据结构看起来由通用的 Python 列表、字典、字符串等组成，但这些实际上都是从基本类型派生的类。这允许我们将每个元素的属性（如果有）存储在字典 my_element.attributes 中，并将标签名称存储在 my_element.tag 中。

Bio.Entrez.parse(source, validate=True, escape=False, ignore_errors=False)

将来自 NCBI Entrez 实用程序的 XML 文件解析为 python 对象。

此函数解析由 NCBI 的 Entrez 实用程序创建的 XML 文件，返回 Python 列表和字典的多级数据结构。此函数适用于可以（在 Python 中）表示为单个记录列表的 XML 文件。虽然“read”读取整个文件并返回单个 Python 列表，“parse”是一个生成器函数，它逐个返回记录。因此，此函数特别适用于解析大型文件。

NCBI 的 Entrez 实用程序返回的大多数 XML 文件都可以通过此函数解析，前提是其 DTD 可用。Biopython 包含大多数常用 Entrez 实用程序的 DTD。

参数source必须是以二进制模式打开的文件或类文件对象，或文件名。解析器从 XML 文件中检测编码，并使用它将 XML 中的所有文本转换为正确的 Unicode 字符串。Bio.Entrez 中访问 NCBI Entrez 的函数将自动以二进制模式返回 XML 数据。对于文件，在打开文件时使用模式“rb”，如

>>> from Bio import Entrez
>>> path = "Entrez/pubmed1.xml"
>>> stream = open(path, "rb")  # opened in binary mode
>>> records = Entrez.parse(stream)
>>> for record in records:
...     print(record['MedlineCitation']['Article']['Journal']['Title'])
...
Social justice (San Francisco, Calif.)
Biochimica et biophysica acta
>>> stream.close()

或者，您可以直接使用文件名，如

>>> records = Entrez.parse(path)
>>> for record in records:
...     print(record['MedlineCitation']['Article']['Journal']['Title'])
...
Social justice (San Francisco, Calif.)
Biochimica et biophysica acta

这更安全，因为文件流将在所有记录读取完毕后或发生错误时自动关闭。

如果 validate 为 True（默认值），解析器将根据 DTD 验证 XML 文件，如果 XML 文件包含 DTD 中没有表示的标签，则会引发错误。如果 validate 为 False，解析器将简单地跳过这些标签。

如果 escape 为 True，则所有非法的 HTML 字符都将被替换为 HTML 转义字符，以确保返回的字符串是有效的 HTML 片段。例如，小于号（<）将被替换为 &lt;。如果 escape 为 False（默认值），则字符串将按原样返回。

如果 ignore_errors 为 False（默认值），则 XML 文件中的任何错误消息都将引发 RuntimeError。如果 ignore_errors 为 True，则错误消息将被存储为 ErrorElement 项，而不会引发异常。

虽然数据结构看起来由通用的 Python 列表、字典、字符串等组成，但这些实际上都是从基本类型派生的类。这允许我们将每个元素的属性（如果有）存储在字典 my_element.attributes 中，并将标签名称存储在 my_element.tag 中。