Bio.SearchIO 包

子包

子模块

模块内容

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

SearchIO 子模块为各种序列搜索程序的输出提供解析器、索引器和写入器。它提供了类似于 SeqIO 和 AlignIO 的 API,具有以下主要功能:parsereadto_dictindexindex_dbwriteconvert

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 只是解析给定的输出文件,并使用 parsewrite 函数将其写入另一个文件。

请注意,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 格式)。支持有或没有标题的变体。

    PSL + 序列 (PSLX) 也受支持。

  • hmmer3-tab - HMMER3 表格输出。

  • hmmer3-domtab - HMMER3 域表输出。使用此格式时,

    程序名称必须指定。例如,要解析 hmmscan 输出,名称应为 'hmmscan-domtab'。

支持解析和索引

  • exonerate-text - Exonerate 纯文本输出。

  • exonerate-vulgar - Exonerate 低俗行。

  • exonerate-cigar - Exonerate 雪茄行。

  • 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 对象加载到内存中,因此可能不适合处理包含许多查询的文件。在这种情况下,建议使用 indexindex_db

从 Python 3.7 开始,默认的字典类会维护键的顺序,这意味着此字典将反映传递给它的记录的顺序。对于 CPython 和 PyPy,这已经在 Python 3.6 中实现,因此实际上你始终可以假设记录顺序被保留。

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

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

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

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

  • key_function - 可选的回调函数,当给定一个

    QueryResult 应返回字典的唯一键。

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

Index 返回一个伪字典对象,其中 QueryResult 对象作为其值,字符串标识符作为其键。此函数主要用于处理大型搜索输出文件,因为它可以比使用 parse 或 read 更快地访问任何给定的 QueryResult 对象。

Index 通过在内存中存储文件中所有查询的起始位置来工作。当用户请求访问查询时,此函数将跳转到其起始位置,解析整个查询,并将其作为 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 函数是 parsewrite 的快捷函数。它与 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)

鉴于不同的搜索输出文件提供不同的统计信息和不同级别的细节,convert 函数仅限于转换具有相同统计信息以及转换为具有相同或更低级别的细节的格式。

例如,无法将 BLAST+ XML 输出转换为 HMMER 表格文件,因为这是两种具有不同统计信息类型的搜索程序。理论上,你可以提供 HMMER 表格文件所需的必要值(例如条件 e 值、包络坐标等)。但是,这些值可能没有太大的意义,因为它们不是真正的 HMMER 计算值。

另一个例子是将 BLAST+ XML 转换为 BLAST+ 表格文件。这是可能的,因为 BLAST+ XML 提供了创建 BLAST+ 表格文件所需的所有值。但是,反向转换可能无法实现。XML 文件中包含更多表格文件中没有的细节(例如 lambda 和 kappa 值)。