Bio.SearchIO 套件

子套件

子模組

模組內容

用於序列搜尋程式輸出的 Biopython 介面。

SearchIO 子模組為各種序列搜尋程式的輸出提供了解析器、索引器和寫入器。它提供了一個類似於 SeqIO 和 AlignIO 的 API，具有以下主要功能： parse、read、to_dict、index、index_db、write 和 convert。

SearchIO 將搜尋輸出檔案的內容解析為四個巢狀物件的層次結構：QueryResult、Hit、HSP 和 HSPFragment。它們各自模擬了搜尋輸出檔案的一部分。

  • QueryResult 代表一個搜尋查詢。這是輸入函數返回的主要物件，它包含所有其他物件。

  • Hit 代表一個資料庫命中。

  • HSP 代表命中中的高分對齊區域。

  • HSPFragment 代表 HSP 內部的連續對齊。

除了上述四個物件外，SearchIO 還與 SeqRecord 物件 (請參閱 SeqIO) 和 MultipleSeqAlignment 物件 (請參閱 AlignIO) 緊密整合。SeqRecord 物件用於儲存實際匹配的命中和查詢序列，而 MultipleSeqAlignment 物件則儲存它們之間的對齊。

這些物件的功能及其範例用法詳情可在其各自的文件中找到。

輸入

解析搜尋輸出檔案的主要函數是 Bio.SearchIO.parse(…)。此函數會解析給定的搜尋輸出檔案，並返回一個產生器物件，該物件每次迭代會產生一個 QueryResult 物件。

parse 接受兩個引數：1) 輸入檔案 (搜尋輸出檔案) 的檔案控制代碼或檔案名稱，以及 2) 格式名稱。

>>> from Bio import SearchIO
>>> for qresult in SearchIO.parse('Blast/mirna.xml', 'blast-xml'):
...     print("%s %s" % (qresult.id, qresult.description))
...
33211 mir_1
33212 mir_2
33213 mir_3

SearchIO 也提供了 Bio.SearchIO.read(…) 函數，該函數適用於僅包含一個查詢的搜尋輸出檔案。read 會返回一個 QueryResult 物件，如果來源檔案包含多個查詢，則會引發例外狀況。

>>> qresult = SearchIO.read('Blast/xml_2226_blastp_004.xml', 'blast-xml')
>>> print("%s %s" % (qresult.id, qresult.description))
...
gi|11464971:4-101 pleckstrin [Mus musculus]

>>> SearchIO.read('Blast/mirna.xml', 'blast-xml')
Traceback (most recent call last):
...
ValueError: ...

若要存取大型輸出檔案的搜尋結果，您可以使用索引函數 Bio.SearchIO.index(…) 或 Bio.SearchIO.index_db(…)。它們與 SeqIO 和 AlignIO 中的對應函數具有類似的介面，並額外提供格式特定的可選關鍵字引數。

輸出

SearchIO 支援多種格式的寫入，可透過 Bio.SearchIO.write(…) 函數存取。此函數會返回一個包含四個數字的元組：寫入的 QueryResult、Hit、HSP 和 HSPFragment 的數量。

qresults = SearchIO.parse('Blast/mirna.xml', 'blast-xml')
SearchIO.write(qresults, 'results.tab', 'blast-tab')
<stdout> (3, 239, 277, 277)

請注意，不同的寫入器可能需要 SearchIO 物件的不同屬性值。這將可寫入搜尋結果的範圍限制為具有所需屬性的搜尋結果。

例如，用於 HMMER 網域表格輸出的寫入器需要來自每個 HSP 物件的條件 e 值屬性。如果您嘗試以 HMMER 網域表格格式寫入，而您的 HSP 沒有此屬性，則會引發例外狀況。

轉換

SearchIO 提供了一個捷徑函數 Bio.SearchIO.convert(…)，用於將給定的檔案轉換為另一種格式。在幕後，convert 只會解析給定的輸出檔案，並使用 parse 和 write 函數將其寫入另一個檔案。

請注意，Bio.SearchIO.write(…) 中的相同限制也適用於 convert 函數。

慣例

建立 SearchIO 的主要目標是在不同的搜尋輸出檔案之間建立一個通用的、易於使用的介面。因此，我們也為 SearchIO 建立了一些超出通用物件模型的慣例/標準。這些慣例適用於 SearchIO 解析的所有檔案，無論它們各自的格式為何。

Python 式的序列座標

在儲存序列座標 (起始和結束值) 時，SearchIO 會使用 Python 式的切片慣例：從零開始且半開區間。例如，如果 BLAST XML 輸出檔案中 HSP 的起始和結束座標為 10 和 28，則在 SearchIO 中它們將變為 9 和 28。起始座標變為 9 是因為 Python 索引從零開始，而結束座標保持 28 不變，因為 Python 切片會省略區間中的最後一個項目。

除了讓您享有標準化的好處之外，此慣例也使座標可用於切片序列。例如，給定完整的查詢序列以及 HSP 的起始和結束座標，可以使用這些座標來提取導致資料庫命中的查詢序列的一部分。

當這些物件使用 SearchIO.write(…) 寫入輸出檔案時，座標值會還原為各自格式的慣例。使用上面的範例，如果 HSP 會寫入 XML 檔案，則起始和結束座標將再次變為 10 和 28。

序列座標順序

某些搜尋輸出格式會根據序列的鏈反轉起始和結束座標序列。

在 SearchIO 中，起始座標始終小於結束座標，無論它們的原始鏈如何。這可確保在使用座標切片完整序列時保持一致性。

請注意，此座標順序慣例僅在 HSPFragment 層級強制執行。如果一個 HSP 物件有多個 HSPFragment 物件，則每個個別的片段都會符合此慣例。但是 HSP 物件內片段的順序遵循搜尋輸出檔案使用的順序。

與座標樣式慣例類似，當使用 Bio.SearchIO.write(…) 寫入物件時，起始和結束座標的順序會還原為它們各自的格式。

框和鏈值

SearchIO 僅允許 -1、0、1 和 None 作為鏈值。對於框，唯一允許的值是 -3 到 3 (含) 的整數和 None。這兩者都是 Biopython 的標準慣例。

支援格式

以下是 SearchIO 支援的搜尋程式輸出格式的清單。

支援解析、索引和寫入

  • blast-tab - BLAST+ 表格輸出。支援不含註解的變體

    (-m 6 旗標) 和含註解的變體 (-m 7 旗標)。

  • blast-xml - BLAST+ XML 輸出。

  • blat-psl - BLAT 的預設輸出 (PSL 格式)。支援含標頭或

    不含標頭的變體。也支援 PSLX (PSL + 序列)。

  • hmmer3-tab - HMMER3 表格輸出。

  • hmmer3-domtab - HMMER3 網域表格輸出。使用此格式時，

    必須指定程式名稱。例如，對於解析 hmmscan 輸出，名稱應為「hmmscan-domtab」。

支援解析和索引

  • exonerate-text - Exonerate 純文字輸出。

  • exonerate-vulgar - Exonerate vulgar 行。

  • exonerate-cigar - Exonerate cigar 行。

  • fasta-m10 - Bill Pearson 的 FASTA -m 10 輸出。

  • hmmer3-text - HMMER3 一般文字輸出格式。支援的 HMMER3

    子程式為 hmmscan、hmmsearch 和 phmmer。

  • hmmer2-text - HMMER2 一般文字輸出格式。支援的 HMMER2

    子程式為 hmmpfam、hmmsearch。

支援解析

  • hhsuite2-text - HHSUITE 純文字輸出。

這些格式中的每一種都具有不同的關鍵字引數，可用於主要的 SearchIO 函數。更多詳細資訊和範例可在每種格式的文件中找到。

Bio.SearchIO.read(handle, format=None, **kwargs)

將包含一個查詢的搜尋輸出檔案轉換為單一 QueryResult。

  • handle - 檔案的控制代碼，或檔案名稱字串。

  • format - 小寫字串，表示支援的格式之一。

  • kwargs - 格式特定的關鍵字引數。

read 用於解析包含一個查詢的搜尋輸出檔案

>>> from Bio import SearchIO
>>> qresult = SearchIO.read('Blast/xml_2226_blastp_004.xml', 'blast-xml')
>>> print("%s %s" % (qresult.id, qresult.description))
...
gi|11464971:4-101 pleckstrin [Mus musculus]

如果給定的控制代碼沒有結果，將會引發例外

>>> from Bio import SearchIO
>>> qresult = SearchIO.read('Blast/tab_2226_tblastn_002.txt', 'blast-tab')
Traceback (most recent call last):
...
ValueError: No query results found in handle

同樣地，如果給定的控制代碼有多個結果，將會引發例外

>>> from Bio import SearchIO
>>> qresult = SearchIO.read('Blast/tab_2226_tblastn_001.txt', 'blast-tab')
Traceback (most recent call last):
...
ValueError: More than one query result found in handle

如同 parse，read 也可能會接受取決於搜尋輸出檔案格式的關鍵字引數。

Bio.SearchIO.parse(handle, format=None, **kwargs)

以 QueryResult 物件的形式迭代搜尋工具輸出檔案。

引數

  • handle - 檔案的控制代碼，或檔案名稱字串。

  • format - 小寫字串，表示支援的格式之一。

  • kwargs - 格式特定的關鍵字引數。

此函式用於迭代給定搜尋輸出檔案中的每個查詢

>>> from Bio import SearchIO
>>> qresults = SearchIO.parse('Blast/mirna.xml', 'blast-xml')
>>> qresults
<generator object ...>
>>> for qresult in qresults:
...     print("Search %s has %i hits" % (qresult.id, len(qresult)))
...
Search 33211 has 100 hits
Search 33212 has 44 hits
Search 33213 has 95 hits

根據檔案格式，parse 也可能會接受額外的關鍵字引數，以修改格式解析器的行為。以下是一個簡單的範例，其中關鍵字引數啟用解析帶有註解的 BLAST 表格輸出檔案

>>> from Bio import SearchIO
>>> for qresult in SearchIO.parse('Blast/mirna.tab', 'blast-tab', comments=True):
...     print("Search %s has %i hits" % (qresult.id, len(qresult)))
...
Search 33211 has 100 hits
Search 33212 has 44 hits
Search 33213 has 95 hits
Bio.SearchIO.to_dict(qresults, key_function=None)

將 QueryResult 迭代器或列表轉換為字典。

  • qresults - 回傳 QueryResult 物件的可迭代物件。

  • key_function - 選用的回呼函式，當給定一個

    QueryResult 物件時，應回傳字典的唯一鍵。預設為使用結果的 .id。

此函式可使用識別符號從單一搜尋輸出檔案存取 QueryResult 物件。

>>> from Bio import SearchIO
>>> qresults = SearchIO.parse('Blast/wnts.xml', 'blast-xml')
>>> search_dict = SearchIO.to_dict(qresults)
>>> list(search_dict)
['gi|195230749:301-1383', 'gi|325053704:108-1166', ..., 'gi|53729353:216-1313']
>>> search_dict['gi|156630997:105-1160']
QueryResult(id='gi|156630997:105-1160', 5 hits)

預設情況下，字典鍵是 QueryResult 的字串 ID。可以透過提供一個回呼函式來更改，該函式會回傳想要的識別符號。以下範例使用一個函式來移除 QueryResult ID 開頭的 'gi|' 部分。

>>> from Bio import SearchIO
>>> qresults = SearchIO.parse('Blast/wnts.xml', 'blast-xml')
>>> key_func = lambda qresult: qresult.id.split('|')[1]
>>> search_dict = SearchIO.to_dict(qresults, key_func)
>>> list(search_dict)
['195230749:301-1383', '325053704:108-1166', ..., '53729353:216-1313']
>>> search_dict['156630997:105-1160']
QueryResult(id='gi|156630997:105-1160', 5 hits)

請注意，回呼函式不會變更 QueryResult 的 ID 值。它只會變更用於檢索相關 QueryResult 的索引鍵值。

由於此函式會將所有 QueryResult 物件載入記憶體，因此可能不適合處理包含大量查詢的檔案。在這種情況下，建議您使用 index 或 index_db。

自 Python 3.7 起，預設的 dict 類別會維護索引鍵順序，這表示此字典將反映提供給它的記錄順序。對於 CPython 和 PyPy，Python 3.6 已實作此功能，因此您可以一直假設記錄順序會被保留。

Bio.SearchIO.index(filename, format=None, key_function=None, **kwargs)

索引搜尋輸出檔案，並傳回類似字典的物件。

  • filename - 字串，提供要索引的檔案名稱

  • format - 小寫字串，表示支援的格式之一。

  • key_function - 選用的回呼函式，當給定一個

    QueryResult 應回傳字典的唯一鍵。

  • kwargs - 格式特定的關鍵字引數。

索引會傳回一個偽字典物件，其中 QueryResult 物件作為其值，字串識別符號作為其索引鍵。此函式主要用於處理大型搜尋輸出檔案，因為它能夠比使用 parse 或 read 更快地存取任何給定的 QueryResult 物件。

索引的工作方式是在記憶體中儲存檔案中所有查詢的起始位置。當使用者請求存取查詢時，此函式會跳到其起始位置，解析整個查詢，並將其回傳為 QueryResult 物件

>>> from Bio import SearchIO
>>> search_idx = SearchIO.index('Blast/wnts.xml', 'blast-xml')
>>> search_idx
SearchIO.index('Blast/wnts.xml', 'blast-xml', key_function=None)
>>> sorted(search_idx)
['gi|156630997:105-1160', 'gi|195230749:301-1383', ..., 'gi|53729353:216-1313']
>>> search_idx['gi|195230749:301-1383']
QueryResult(id='gi|195230749:301-1383', 5 hits)
>>> search_idx.close()

如果檔案是 BGZF 壓縮的，則會自動偵測到。不支援普通的 GZIP 檔案

>>> from Bio import SearchIO
>>> search_idx = SearchIO.index('Blast/wnts.xml.bgz', 'blast-xml')
>>> search_idx
SearchIO.index('Blast/wnts.xml.bgz', 'blast-xml', key_function=None)
>>> search_idx['gi|195230749:301-1383']
QueryResult(id='gi|195230749:301-1383', 5 hits)
>>> search_idx.close()

您可以提供自訂回呼函式來更改預設的識別符號字串。此函式應接受 QueryResult ID 字串作為輸入，並回傳其修改版本。

>>> from Bio import SearchIO
>>> key_func = lambda id: id.split('|')[1]
>>> search_idx = SearchIO.index('Blast/wnts.xml', 'blast-xml', key_func)
>>> search_idx
SearchIO.index('Blast/wnts.xml', 'blast-xml', key_function=<function <lambda> at ...>)
>>> sorted(search_idx)
['156630997:105-1160', ..., '371502086:108-1205', '53729353:216-1313']
>>> search_idx['156630997:105-1160']
QueryResult(id='gi|156630997:105-1160', 5 hits)
>>> search_idx.close()

請注意，回呼函式不會變更 QueryResult 的 ID 值。它只會變更用於檢索相關 QueryResult 的索引鍵值。

Bio.SearchIO.index_db(index_filename, filenames=None, format=None, key_function=None, **kwargs)

將多個搜尋輸出檔案索引到 SQLite 資料庫中。

  • index_filename - SQLite 檔案名稱。

  • filenames - 指定要索引的檔案的字串清單，或者當

    索引單一檔案時，這可以作為字串給定。（如果重新載入現有的索引，則為選用，但必須符合）

  • format - 小寫字串，表示支援的格式之一。

    （如果重新載入現有的索引，則為選用，但必須符合）

  • key_function - 選用的回呼函式，當給定一個

    QueryResult 識別符號字串應回傳字典的唯一鍵。

  • kwargs - 格式特定的關鍵字引數。

index_db 函式與 index 類似，在於它會索引搜尋輸出檔案中所有查詢的起始位置。主要差異在於，這些索引不會儲存在記憶體中，而是作為 SQLite 資料庫檔案寫入磁碟。這允許索引在 Python 工作階段之間持續存在。這讓使用者可以存取檔案中的任何查詢，而無需任何索引額外負荷，前提是該檔案已至少索引過一次。

>>> from Bio import SearchIO
>>> idx_filename = ":memory:" # Use a real filename, this is in RAM only!
>>> db_idx = SearchIO.index_db(idx_filename, 'Blast/mirna.xml', 'blast-xml')
>>> sorted(db_idx)
['33211', '33212', '33213']
>>> db_idx['33212']
QueryResult(id='33212', 44 hits)
>>> db_idx.close()

index_db 也可以索引多個檔案，並將它們儲存在同一個資料庫中，方便使用者將多個搜尋檔案分組，並從單一介面存取它們。

>>> from Bio import SearchIO
>>> idx_filename = ":memory:" # Use a real filename, this is in RAM only!
>>> files = ['Blast/mirna.xml', 'Blast/wnts.xml']
>>> db_idx = SearchIO.index_db(idx_filename, files, 'blast-xml')
>>> sorted(db_idx)
['33211', '33212', '33213', 'gi|156630997:105-1160', ..., 'gi|53729353:216-1313']
>>> db_idx['33212']
QueryResult(id='33212', 44 hits)
>>> db_idx.close()

一個常見的實用範例是，如果您有一組大型的查詢序列（例如一萬個），您可以將其分成十個查詢檔案，每個檔案有一千個序列，以便在叢集上執行十個單獨的 BLAST 作業。您可以使用 index_db 將這十個 BLAST 輸出檔案一起索引，以便順暢地存取所有結果，就像一個字典一樣。

請注意，使用 ':memory:' 而不是索引檔案名稱會告訴 SQLite 將索引資料庫保留在記憶體中。這對於快速測試很有用，但使用 Bio.SearchIO.index(…) 函式反而會使用較少的記憶體。

支援 BGZF 壓縮檔案，並且會自動偵測。不支援普通的 GZIP 壓縮檔案。

另請參閱 Bio.SearchIO.index()、Bio.SearchIO.to_dict() 和 Python 模組 glob，它對於建立檔案清單很有用。

Bio.SearchIO.write(qresults, handle, format=None, **kwargs)

以給定的格式將 QueryResult 物件寫入檔案。

  • qresults - 回傳 QueryResult 物件的迭代器或單一

    QueryResult 物件。

  • handle - 檔案的控制代碼，或檔案名稱字串。

  • format - 小寫字串，表示支援的格式之一。

  • kwargs - 格式特定的關鍵字引數。

write 函式會將 QueryResult 物件寫入給定的輸出控制代碼/檔案名稱。您可以向其提供單一 QueryResult 物件，或回傳一個或多個 QueryResult 物件的可迭代物件。在這兩種情況下，此函式都會回傳一個包含四個值的元組：寫入輸出檔案的 QueryResult、Hit、HSP 和 HSPFragment 物件數量

from Bio import SearchIO
qresults = SearchIO.parse('Blast/mirna.xml', 'blast-xml')
SearchIO.write(qresults, 'results.tab', 'blast-tab')
<stdout> (3, 239, 277, 277)

可以使用格式特定的關鍵字引數來調整不同格式的輸出。以下範例會寫入帶有標頭的 BLAT PSL 輸出檔案

from Bio import SearchIO
qresults = SearchIO.parse('Blat/psl_34_001.psl', 'blat-psl')
SearchIO.write(qresults, 'results.tab', 'blat-psl', header=True)
<stdout> (2, 13, 22, 26)
Bio.SearchIO.convert(in_file, in_format, out_file, out_format, in_kwargs=None, out_kwargs=None)

在兩種搜尋輸出格式之間轉換，並回傳記錄數。

  • in_file - 輸入檔案的控制代碼，或檔案名稱字串。

  • in_format - 小寫字串，表示輸入檔案的格式。

  • out_file - 輸出檔案的控制代碼，或檔案名稱字串。

  • out_format - 小寫字串，表示輸出檔案的格式。

  • in_kwargs - 輸入函式的關鍵字引數字典。

  • out_kwargs - 輸出函式的關鍵字引數字典。

convert 函式是 parse 和 write 的快捷函式。它具有與 write 相同的回傳類型。格式特定的引數可以傳遞給 convert 函式，但只能以字典的形式傳遞。

這是一個使用 convert 將 BLAST+ XML 檔案轉換為帶有註解的表格檔案的範例。

from Bio import SearchIO
in_file = 'Blast/mirna.xml'
in_fmt = 'blast-xml'
out_file = 'results.tab'
out_fmt = 'blast-tab'
out_kwarg = {'comments': True}
SearchIO.convert(in_file, in_fmt, out_file, out_fmt, out_kwargs=out_kwarg)
<stdout> (3, 239, 277, 277)

由於不同的搜尋輸出檔案提供不同的統計數據和詳細程度，轉換功能僅限於轉換具有相同統計數據的格式，以及轉換為具有相同或較低詳細程度的格式。

例如，將 BLAST+ XML 輸出轉換為 HMMER 表格檔案是不可能的，因為這是兩種具有不同種類統計數據的搜尋程式。理論上，您可以提供 HMMER 表格檔案所需的必要值（例如，條件 e 值、信封座標等）。然而，這些值可能沒有什麼意義，因為它們不是真正的 HMMER 計算值。

另一個例子是將 BLAST+ XML 轉換為 BLAST+ 表格檔案。這是可行的，因為 BLAST+ XML 提供了建立 BLAST+ 表格檔案所需的所有值。但是，反向轉換可能不可行。XML 檔案中涵蓋了更多在表格檔案中找不到的詳細資訊（例如，lambda 和 kappa 值）。