Bio.SearchIO包

子包

子模块

模块内容

用于序列搜索程序输出的Biopython接口。

SearchIO子模块为各种序列搜索程序的输出提供解析器、索引器和写入器。它提供了类似于SeqIO和AlignIO的API，主要功能如下： parse , read , to_dict , index , index_db , write ，而且 convert .

SearchIO将搜索输出文件的内容解析为由四个嵌套对象组成的层次结构：CredyReport、Hit、SPP和HSPFragment。它们中的每个都对搜索输出文件的一部分进行建模：

  • CredyResponse代表搜索查询。这是输入函数返回的主要对象，并且它包含所有其他对象。

  • 命中代表数据库命中，

  • 热休克蛋白代表命中中的高分对齐区域，

  • HSPFragment代表HSPs内的连续排列

除了上面的四个对象之外，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. writer（.）访问功能该函数返回由四个数字组成的二元组：编写的CheckResponse、Hit、SPP和HSPFragment的编号：：

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

请注意，不同的编写器可能需要SearchIO对象的不同属性值。这将可写搜索结果的范围限制为具有所需属性的搜索结果。

例如，HMMER域表输出的编写器需要每个SPP对象等的条件e值属性。如果您尝试写入HMMER域表格式，但您的MPS没有此属性，则会引发异常。

转换

SearchIO提供快捷功能Bio.SearchIO.convert（.）将给定文件转换为另一种格式。引擎盖下， convert 只需解析给定的输出文件并使用 parse 和 write 功能协调发展的

请注意，Bio.SearchIO. writer（.）中也存在相同的限制也适用于转换功能。

公约

创建SearchIO的主要目标是在不同的搜索输出文件中拥有一个通用、易于使用的界面。因此，我们还为SearchIO创建了一些超越通用对象模型的约定/标准。这些约定适用于SearchIO解析的所有文件，无论其单独的格式如何。

Python式序列坐标

存储序列坐标（开始和结束值）时，SearchIO使用Python风格的切片约定：从零开始和半开间隔。例如，如果在BLASTML输出文件中，热休克蛋白的开始和结束坐标是10和28，那么在SearchIO中它们将变成9和28。开始坐标变为9，因为Python索引从零开始，而结束坐标保持28，因为Python切片在一定时间内省略了最后一项。

除了为您提供标准化的好处之外，该约定还使坐标可用于切片序列。例如，给定完整的查询序列以及热休克蛋白的开始和结束坐标，可以使用这些坐标来提取导致数据库命中的部分查询序列。

当这些对象使用SearchIO. writer（.）写入输出文件时，坐标值被恢复为其各自格式的惯例。使用上面的例子，如果将Hep写入到一个HTML文件，则开始和结束坐标将再次变为10和28。

序列坐标顺序

一些搜索输出格式根据序列链颠倒开始和结束坐标序列。

在SearchIO中，开始坐标始终小于结束坐标，无论其起源链如何。这确保了使用坐标切片完整序列时的一致性。

请注意，此坐标顺序约定仅在HSPFragment级别中强制执行。如果一个SPP对象具有多个HSPFragment对象，则每个单独的片段都将符合此约定。但SPP对象内片段的顺序遵循搜索输出文件使用的顺序。

与坐标样式惯例类似，当使用Bio.SearchIO. writer（.）编写对象时，开始和结束坐标的顺序将恢复为各自的格式。

框架和股值

SearchIO只允许-1，0，1和None作为strand值。对于帧，唯一允许的值是从-3到3（含）的整数和“无”。这两个都是标准的Biopython约定。

支持的格式

以下是SearchIO支持的搜索程序输出格式列表。

支持解析、索引和编写：

  • 爆炸标签 - AMPS+表格输出。两个变体都没有评论

    (-m 6标志）和带有评论（-m 7标志）的支持。

  • blast-html - BST + HTML输出。

  • 布拉特-psl - BLAT（PSL格式）的默认输出。带有或的变体

    两者都支持没有标题。还支持PSLK（PSL +序列）。

  • hmmer 3-tab - HMMER 3表输出。

  • hmmer 3-domtab - HMMER 3域表输出。使用此格式时，

    必须指定程序名称。例如，对于解析hmmscan-domtab输出，名称应为“hmmscan-domtab”。

支持解析和索引：

  • 免罪文本 - 免除纯文本输出的责任。

  • 开脱-粗俗-开脱粗俗路线。

  • 无罪-雪茄-无罪雪茄系列。

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

  • hmmer 3-text - HMMER 3常规文本输出格式。支持的HMMER 3

    子程序是hmmscan、hmmsearch和phmmer。

  • hmmer 2-text - HMMER 2常规文本输出格式。支持的HMMER 2

    子程序是hmmpfam、hmmsearch。

支持解析：

  • Hhsuite 2-text - HHSUITE纯文本输出。

这些格式中的每种格式都有不同的关键字参数，可供主SearchIO函数使用。更多详细信息和示例请参阅该格式的每个文档。

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

将包含一个查询的搜索输出文件转换为一个CredyReport。

  • handle -文件的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)

将搜索工具输出文件作为WRyResponse对象进行迭代。

论点：

  • handle -文件的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 还可以接受修改格式解析器行为的附加关键字参数。这是一个简单的示例，其中关键字参数可以解析已注释的BST表格输出文件：

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

将WReyResponse迭代器或列表转换为字典。

  • qrets - 可迭代的返回CredyResponse对象。

  • key_函数-可选的回调函数，当给定

    SecureResponse对象应返回字典的唯一键。请使用结果的.id。

此函数允许使用单个搜索输出文件的标识符访问其SecureResponse对象。

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

默认情况下，字典关键字是CredyResponse的字符串ID。这可以通过提供返回所需标识符的回调函数来更改。以下是一个使用删除“gi”的函数的示例|'在查询结果ID的开头部分。

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

请注意，回调函数不会更改CredyResponse的ID值。它仅更改用于检索关联的KYSYS的key值。

由于此函数将所有CredyResponse对象加载到内存中，因此它可能不适合处理包含许多查询的文件。在这种情况下，建议您使用其中之一 index 或 index_db .

自Python 3.7以来，默认的dict类会维护键顺序，这意味着该字典将反映赋予它的记录顺序。对于CPython和PyPy，这已经在Python 3.6中实现了，因此实际上您可以始终假设记录顺序被保留。

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

对搜索输出文件进行索引并返回类似字典的对象。

  • 文件名 - 给出要索引的文件名称的字符串

  • 格式 - 大小写字符串表示支持的格式之一。

  • key_函数-可选的回调函数，当给定

    CredyResponse应该返回字典的唯一密钥。

  • kwargs - 特定于服务器的关键字参数。

Index返回一个伪字典对象，其中CheckResponse对象作为其值，字符串标识符作为其键。该函数主要适用于处理大型搜索输出文件，因为它可以比使用解析或读取更快地访问任何给定的Creduit对象。

索引的工作原理是将文件中所有查询的开始位置存储在内存中。当用户请求访问查询时，此函数将跳转到其开始位置，解析整个查询，并将其作为CheckResponse对象返回：

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

您可以提供自定义回调函数来更改默认标识符字符串。此函数应接受CheckResponse 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()

请注意，回调函数不会更改CredyResponse的ID值。它仅更改用于检索关联的KYSYS的key值。

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

将多个搜索输出文件编入SQLite数据库。

  • index_file-SQLite文件名。

  • 文件名 - 指定要索引的文件或何时索引的字符串列表

    对单个文件进行索引，这可以作为字符串给出。（如果重新加载现有索引，则可选，但必须匹配）

  • 格式 - 大小写字符串表示支持的格式之一。

    （如果重新加载现有索引，则可选，但必须匹配）

  • key_函数-可选的回调函数，当给定

    CredyResponse标识符字符串应返回字典的唯一键。

  • 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()

这很有帮助的一个常见例子是，如果您有一大组查询序列（比如一万个），您将其分成十个查询文件，每个查询文件包含一千个序列，以便在集群上作为十个独立的BST作业运行。你可以用 index_db 将十个BST输出文件索引在一起，以便将所有结果作为一个字典无缝访问。

请注意，“：内存：”而不是索引文件名告诉SQLite将索引数据库保存在内存中。这对于快速测试很有用，但使用Bio.SearchIO.index（.）相反，函数会使用更少的内存。

支持BGZR压缩文件并自动检测。不支持普通GZip压缩文件。

另请参阅Bio.SearchIO.index（）、Bio.SearchIO.to_dict（）和Python模块gob，该模块对于构建文件列表很有用。

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

以给定格式将WReyResponse对象写入文件。

  • qresults -返回QueryResult对象或单个

    CredyResponse对象。

  • 手柄 - 文件的手柄，或字符串形式的文件名。

  • 格式 - 大小写字符串表示支持的格式之一。

  • kwargs - 特定于收件箱的关键字参数。

的 write 函数将CredyResponse对象写入给定的输出手柄/文件名。您可以为它提供一个单独的SecureResponse对象或一个返回一个或多个SecureResponse对象的迭代对象。在这两种情况下，该函数都将返回由四个值组成的二元组：它写入输出文件的Creduit、Hit、SPP和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_form-表示输入文件格式的大写字符串。

  • out_file - 输出文件的手柄，或字符串形式的文件名。

  • out_form-表示输出文件格式的大写字符串。

  • in_kwargs -输入函数的关键字参数词典。

  • out_kwargs -输出函数的关键字参数词典。

转换功能是一个快捷功能 parse 和 write .它的返回类型与 write .特定于收件箱的参数可以传递给convert函数，但只能作为字典传递。

这是一个使用的例子 convert 从AMPS + ML文件转换为带注释的表格文件：：

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计算值。

另一个例子是从BST + HTML转换为BST+表格文件。这是可能的，因为RST + ML提供了创建RST+表格文件所需的所有值。然而，反向转换可能是不可能的。该文档中包含了表格文件中找不到的更多详细信息（例如，Lambda和kappa值）