Bio.Entrez 套件

子模組

模組內容

提供透過 WWW 存取 NCBI 的程式碼。

主要的 Entrez 網頁位於： http://www.ncbi.nlm.nih.gov/Entrez/

Entrez 程式設計工具網頁位於： http://www.ncbi.nlm.nih.gov/books/NBK25501/

此模組提供一些函式，如 efetch（Entrez Fetch 的縮寫），它會將資料以 handle 物件的形式傳回。這是 Python 中用於從檔案或在本例中從遠端網路連線讀取資料的標準介面，並提供如 .read() 的方法或逐行迭代內容。另請參閱 Biopython 教學與手冊中的「什麼是 handle？ 」： https://biopython.dev.org.tw/DIST/docs/tutorial/Tutorial.html https://biopython.dev.org.tw/DIST/docs/tutorial/Tutorial.pdf 這些函式傳回的 handle 可以是文字模式或二進位模式，具體取決於所要求的資料以及 NCBI Entrez 傳回的結果。通常，XML 資料會是二進位模式，而其他資料會是文字模式，這是下游解析器解析資料時所要求的。

與 open(filename) 函式從磁碟檔案取得的 handle 不同，後者具有 .name 屬性，可提供檔案名稱，而 Bio.Entrez 的 handle 則都有 .url 屬性，可提供用於連線到 NCBI Entrez API 的 URL。

epost、efetch 和 esummary 工具會採用「id」參數，該參數對應到一個或多個資料庫 UID（或在「nuccore」或「protein」等序列資料庫的情況下，對應到 accession.version 識別碼）。傳遞給這些函式的「id」關鍵字 Python 值可以是單一 ID，類型為字串或整數，也可以是多個 ID，類型為字串/整數的可迭代物件。您也可以傳遞一個包含多個以逗號分隔之 ID 的單一字串。elink 工具也接受多個 ID，但其引數的處理方式與其他三個不同。如需詳細資訊，請參閱該函式的 docstring。

所有傳送請求至 NCBI Entrez API 的函式都會自動遵守 NCBI 速率限制（沒有 API 金鑰時每秒 3 個請求，有 API 金鑰時每秒 10 個請求），並且在遇到暫時性錯誤（即連線失敗或 HTTP 5XX 程式碼）時會自動重試。預設情況下，Biopython 會在放棄之前最多嘗試三次，並且每次嘗試之間會睡眠 15 秒。您可以設定 Bio.Entrez.max_tries 和 Bio.Entrez.sleep_between_tries 來調整這些參數。

Entrez 模組也提供 XML 解析器，它會將 handle 作為輸入。

變數

  • 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 = "Your.Name.Here@example.org"
>>> handle = Entrez.einfo() # or esearch, efetch, ...
>>> record = Entrez.read(handle)
>>> handle.close()

    其中 record 現在是一個 Python 字典或列表。

  • parse 解析那些可以傳回多個記錄的上述函式傳回的 XML 結果，例如 efetch、esummary 和 elink。典型用法是

    >>> 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

傳回:

結果的 Handle。

引發:

urllib.error.URLError – 如果發生網路錯誤。

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

提取 Entrez 結果，並以 handle 的形式回傳。

EFetch 從一個或多個 UI 的列表或集合，或從使用者的環境中，以請求的格式檢索記錄。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EFetch

簡短範例

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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。

傳回:

結果的 Handle。

引發:

urllib.error.URLError – 如果發生網路錯誤。

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

執行 Entrez 搜尋，並回傳結果的 handle。

ESearch 會搜尋並檢索主要 ID（用於 EFetch、ELink 和 ESummary）和詞彙翻譯，並可選擇保留結果供未來在使用者環境中使用。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESearch

簡短範例

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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
傳回:

結果的 Handle，一律為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

檢查是否有連結的外部文章，並回傳 handle。

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 將在結果中混合在一起。

此範例尋找與 PubMed 資料庫中 Biopython 應用程式註釋條目相關的文章

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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 教學中有更詳細的說明。

傳回:

結果的 Handle，預設為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

Bio.Entrez.einfo(**keywds)

以結果 handle 的形式回傳 Entrez 資料庫的摘要。

EInfo 提供每個 Entrez 資料庫的欄位名稱、索引詞彙計數、上次更新和可用的連結。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EInfo

簡短範例

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> record = Entrez.read(Entrez.einfo())
>>> 'pubmed' in record['DbList']
True
傳回:

結果的 Handle，預設為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

Bio.Entrez.esummary(**keywds)

以結果 handle 的形式檢索文件摘要。

ESummary 從主要 ID 列表或從使用者環境中檢索文件摘要。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESummary

此範例探索更多關於結構資料庫中條目 19923 的資訊

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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
傳回:

結果的 Handle，預設為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

Bio.Entrez.egquery(**keywds)

為全域搜尋提供 Entrez 資料庫計數（已棄用）。

EGQuery 為使用 Global Query 的單一搜尋提供 XML 格式的 Entrez 資料庫計數。但是，NCBI 不再維護此功能，並建議對每個感興趣的資料庫使用 esearch。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EGQuery

這個基於 Biopython 教學中較長版本的快速範例僅檢查 PubMedCentral 中是否有超過 60 個與 'Biopython' 匹配的項目

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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
傳回:

結果的 Handle，預設為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

Bio.Entrez.espell(**keywds)

以結果 handle 的形式檢索拼寫建議。

ESpell 檢索拼寫建議（如果可用）。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ESpell

簡短範例

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> record = Entrez.read(Entrez.espell(term="biopythooon"))
>>> print(record["Query"])
biopythooon
>>> print(record["CorrectedQuery"])
biopython
傳回:

結果的 Handle，預設為 XML 格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

Bio.Entrez.ecitmatch(**keywds)

檢索輸入引文的 PMID，並以 handle 的形式回傳。

ECitMatch 檢索與一組輸入引文字串對應的 PubMed ID (PMID)。

有關參數的說明，請參閱線上文件：http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ECitMatch

簡短範例

>>> from Bio import Entrez
>>> Entrez.email = "Your.Name.Here@example.org"
>>> 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()
傳回:

結果的 Handle，預設為純文字格式。

引發:

urllib.error.URLError – 如果發生網路錯誤。

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

將來自 NCBI Entrez Utilities 的 XML 檔案解析為 Python 物件。

此函式會解析由 NCBI 的 Entrez Utilities 建立的 XML 檔案，並傳回 Python 列表和字典的多層資料結構。只要 DTD 可用，此函式就可以解析 NCBI Entrez Utilities 回傳的大多數 XML 檔案。Biopython 包含最常用 Entrez Utilities 的 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 Utilities 的 XML 檔案解析為 Python 物件。

此函式會解析由 NCBI 的 Entrez Utilities 建立的 XML 檔案，並傳回 Python 列表和字典的多層資料結構。此函式適用於（在 Python 中）可以表示為個別記錄列表的 XML 檔案。而 'read' 會讀取整個檔案並傳回單一 Python 列表，'parse' 是一個產生器函式，會逐個回傳記錄。因此，此函式特別適用於解析大型檔案。

只要 DTD 可用，此函式就可以解析 NCBI Entrez Utilities 回傳的大多數 XML 檔案。Biopython 包含最常用 Entrez Utilities 的 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 中。