Bio.SearchIO包

子包

子模块

模块内容

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

SearchIO子模块为各种序列搜索程序的输出提供解析器、索引器和编写器。提供与SeqIO、AlignIO类似的接口，主要功能如下： parse ， read ， to_dict ， index ， index_db ， write ，以及 convert 。

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

  • QueryResult表示搜索查询。这是输入函数返回的主对象，它包含所有其他对象。

  • 命中表示数据库命中，

  • 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-value属性等。如果您尝试写入HMMER域表格式，而您的HSP没有此属性，则会引发异常。

转换

SearchIO提供快捷函数Bio.SearchIO.Convert(.)将给定文件转换为另一种格式。在引擎盖下， convert 属性简单地解析给定的输出文件并将其写入另一个文件。 parse 和 write 功能。

请注意，Bio.SearchIO.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。

序列坐标顺序

某些搜索输出格式根据序列的链反转开始和结束坐标序列。例如，在BLAST纯文本格式中，如果匹配链位于负方向，则开始坐标将始终大于结束坐标。

在SearchIO中，开始坐标始终小于结束坐标，而不考虑它们的原始链。这确保了在使用坐标对完整序列进行切片时的一致性。

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

与坐标样式约定类似，使用Bio.SearchIO.write(.)写入对象时，起始坐标和结束坐标的顺序将恢复为各自的格式。

框架和线束值

SearchIO仅允许-1、0、1和NONE作为串值。对于帧，唯一允许的值是介于-3到3(包括-3和3)之间的整数和NONE。这两个都是标准的Biopython约定。

支持的格式

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

支持解析、索引和写入：

  • BLAST-标签-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纯文本输出。

  • 清白-粗俗-清白粗俗的路线。

  • 免责雪茄-免责雪茄-免责雪茄生产线。

  • FASTA-M10-Bill Pearson的FASTA-M10输出。

  • hmmer3-text-HMMER3常规文本输出格式。支持的HMMER3

    子程序有hmmscan、hmmsearch和phmmer。

  • hmmer2-text-HMMER2常规文本输出格式。支持的HMMER2

    子程序有hmmpfam、hmmsearch。

支持解析：

  • BLAST-Text-BLAST+纯文本输出。

  • hhsuite2-text-HHSUITE纯文本输出。

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

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

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

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

  • 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 results found in handle

喜欢 parse ， read 还可以接受关键字参数，具体取决于搜索输出文件格式。

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

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

参数：

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

  • 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-Iterable返回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 。

从Python3.7开始，默认的DICT类保持键顺序，这意味着该字典将反映提供给它的记录的顺序。对于CPython和PyPy，这已经在Python3.6中实现了，因此您可以始终有效地假设记录顺序是保留的。

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

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

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

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

  • key_function-可选的回调函数，在给定

    QueryResult应该返回字典的唯一键。

  • kwargs-特定于格式的关键字参数。

Index返回一个伪字典对象，其中QueryResult对象作为其值，字符串标识符作为其键。该函数主要用于处理大型搜索输出文件，因为它允许访问任何给定的QueryResult对象，速度比使用parse或read快得多。

索引的工作方式是在内存中将所有查询的开始位置存储在一个文件中。当用户请求访问查询时，此函数将跳到其起始位置，解析整个查询，并将其作为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()

这很有帮助的一个常见示例是，如果您有一个很大的查询序列集(比方说一万个)，您将它们拆分为10个查询文件，每个查询文件包含1000个序列，以便在一个集群上作为10个单独的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对象写入给定格式的文件。

  • qresult-返回QueryResult对象的迭代器或单个

    QueryResult对象。

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

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