Eutils用法总结

好久没更新了，这里都长草了。。。

总结下Eutils的用法，参考《E-utilities Quick Start》，没时间看英文的可以参考下。

简介

Eutils全称是The Entrez Programming Utilities (E-utilities)，是由八个服务器端程序组成的一套编程工具，它提供用于访问NCBI Entrez查询和数据库系统的稳定接口。 这八个工具包括Einfo、ESearch、EPost、ESummary、EFetch、ELink、EGQuery、ESpell（详见表1）。通过这些工具，你可以访问NCBI Entrez所包含的序列、三维结构、文献等所有38个数据库。

表1. 八种Eutils工具

Eutils Name	Entry	Required Parameters	Optional Parameters	Return Format
EInfo	einfo.fcgi		db	xml
ESearch	esearch.fcgi	db term	usehistory WebEnv query_key retstart retmax rettype field datetype reldate mindate, maxdate	xml
EPost	epost.fcgi	db id	WebEnv QueryKey	xml
ESummary	esummary.fcgi	db id WebEnv query_key	retstart retmax version	xml
EFetch	efetch.fcgi	db id WebEnv query_key	retmode retstart retmax rettype strand seq_start seq_stop complexity	xml/text/asn （详情见表2）
ELink	elink.fcgi	db dbfrom cmd id WebEnv query_key	linkname term holding datetype reldate mindate, maxdate	xml
EGQuery	egquery.fcgi	term		xml
ESpell	espell.fcgi	db term		xml

访问地址

Eutils工具使用固定URL地址的形式进行访问，每个工具都有一个固定的访问地址BaseURL，都以EutilsURL开始。

EutilsURL：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/

如：EInfo 的访问地址为：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi

即：BaseURL=EutilsURL + Entry（一个以工具名称命名的Fasta CGI 文件，扩展名为fcgi。什么是Fasta CGI？。。。其实我也不了解）

使用限制

每秒查询次数不能超过3次，大型查询限制在周末和工作日的9:00 PM～5:00 AM，超过次限制会被封IP，除非给eutilities@ncbi.nlm.nih.gov发邮件注册使用eutils服务的软件名称tool和email地址，并在使用服务时以URL参数的形式传入。大量操作最好还是注册一下比较好。

使用示例

通过设置不同的URL参数获取不同的结果，八个工具参数列表如下图所示，参数分为两种，必须参数和可选参数，返回文件格式大多为xml。

• EInfo示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi?db=protein

示例1没有传入参数将列出所有的支持数据库，即示例2中db参数的名字；

示例2将列出protein数据库的基本信息。

• Esearch示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=protein&term=dnapol

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?term=dnapol

示例3：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=protein&term=dnapol&usehistory=y

示例4：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=protein&term=virus&query_key=1&WebEnv=NCID_1_55320436_

130.14.18.48_5553_1335062251_525363903&usehistory=y

示例1传入必须参数，所查询的数据库名称db和要查询的关键词term；示例2仅传入要查询的关键词term，并不是由于db为非必须参数，而是因为db的默认值是pubmed，所以示例2将查询以dnapol为关键词查询pubmed数据库；

示例3使用可选usehistory参数将在服务器端产生一个查询历史记录，结果中将生成WebEnv和query_key值，下一次使用ESearch、ESummary等操作可利用这些参数在这一次查询结果基础上进行操作，这也是Eutils最强大的地方，可以方便的建立自己的工作流程；

示例4中即使用示例3中的查询结果重新查询以virus为关键词的条目，这等价于将示例3中的“term=dnapol”替换为“term=dnapol+virus”的查询结果。

• EPost示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/epost.fcgi?db=protein&id=15718680,157427902,119703751

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/epost.fcgi?db=protein&id=15718680,157427902,119703751&WebEnv=NCID_1_25983036_

165.112.9.24_5553_1335063999_246386066

示例1将三个蛋白质数据库的id号上传到服务器，结果中将生成WebEnv和query_key值，以备后续操作使用；

示例2在给定的WebEnv历史记录上添加给定id号；注：在使用其他Eutils工具，如EFetch，id参数条目数超过限制时，只能使用EPost，先上传需要的id，然后在所使用工具中传入EPost结果中的WebEnv和query_key值。

• ESummary示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=protein&id=15718680,157427902,119703751

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=protein&query_key=1&WebEnv=NCID_1_25983036_

165.112.9.24_5553_1335063999_246386066

示例1列出给定id号的摘要信息；

示例2列出给定查询历史记录中的摘要信息。

注：ESummary中db为必选参数，id和(query_key+WebEnv)二选一。

• EFetch示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=protein&id=15718680,157427902,119703751

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=protein&id=15718680,157427902,119703751&rettype=fasta

示例3：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=protein&id=15718680,157427902,119703751&rettype=fasta&retmode=xml

示例1以text ASN.1格式返回给定id号的蛋白序列文件；

示例2以text fasta格式返回给定id号的蛋白序列文件；

示例3以xml fasta格式返回给定id号的蛋白序列文件。

注：EFetch是获取数据库文件的常用工具，示例1中没有给定rettype和retmode参数，默认为text ASN.1格式，示例2中retmode参数默认为text，示例3中retmode设置为xml，返回xml格式的fasta文件。各数据库支持的返回参数见表2。在EFetch中使用ESearch结果中的query_key和WebEnv参数，可轻松实现普通的Entrez下载操作。

表2. EFetch中各数据库支持的retmode和rettype值 

Record Type	&rettype	&retmode
db = biosample
Full record XML	full, default	xml, default
Full record text	full, default	text
db = biosystems
Full record XML	xml, default	xml, default
db = gds
Summary	summary, default	text, default
db = gene
text ASN.1	null	asn.1, default
XML	null	xml
Gene table	gene_table	text
db = homologene
text ASN.1	null	asn.1, default
XML	null	xml
Alignment scores	alignmentscores	text
FASTA	fasta	text
HomoloGene	homologene	text
db = mesh
Full record	full, default	text, default
db = nuccore, nucest, nucgss, protein or popset
text ASN.1	null	text, default
binary ASN.1	null	asn.1
Full record in XML	native	xml
Accession number(s)	acc	text
FASTA	fasta	text
TinySeq XML	fasta	xml
SeqID string	seqid	text
Additional options for db = nuccore, nucest, nucgss or popset
GenBank flat file	gb	text
GBSeq XML	gb	xml
INSDSeq XML	gbc	xml
Additional option for db = nuccore and protein
Feature table	ft	text
Additional option for db = nuccore
GenBank flat file with full sequence (contigs)	gbwithparts	text
CDS nucleotide FASTA	fasta_cds_na	text
CDS protein FASTA	fasta_cds_aa	text
Additional option for db = nucest
EST report	est	text
Additional option for db = nucgss
GSS report	gss	text
Additional options for db = protein
GenPept flat file	gp	text
GBSeq XML	gp	xml
INSDSeq XML	gpc	xml
db = pmc
XML	null	xml, default
MEDLINE	medline	text
db = pubmed
text ASN.1	null	asn.1, default
XML	null	xml
MEDLINE	medline	text
PMID list	uilist	text
Abstract	abstract	text
db = sequences
text ASN.1	null	text, default
Accession number(s)	acc	text
FASTA	fasta	text
SeqID string	seqid	text
db = snp
text ASN.1	null	asn.1, default
XML	null	xml
Flat file	flt	text
FASTA	fasta	text
RS Cluster report	rsr	text
SS Exemplar list	ssexemplar	text
Chromosome report	chr	text
Genotype XML	genxml	xml
Summary	docset	text
UID list	uilist	text or xml
db = sra
XML	full, default	xml, default
db = taxonomy
XML	null	xml, default
TaxID list	uilist	text or xml

• ELink示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=protein&db=gene&id=15718680,157427902

示例2：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&db=pubmed&id=20210808&cmd=neighbor_score

示例1将返回给定的蛋白id所对应的基因的id；示例2将返回和文章20210808相似的pubmedID，并给出对应的相似性分数。

注：ELink是eutils中一个强大的跨库查询工具，通过cmd参数可以实现各种各样的map功能。如示例1中，cmd默认参数是neighbor，实现简单的将蛋白id映射到对应的基因id的功能。示例2中neighbor_score实现相似文章的搜索。cmd参数的详细功能见表3。

表3. Elink中cmd参数功能详解

参数	功能
neighbor (default)	返回另一个数据库中和给定UID对应的UID。如不设置db相当于设置db=pubmed（默认值）。下同1
neighbor_score	返回同一数据库中和给定UID相似的UID列表及相似性分数。如不设置db相当于设置与dbfrom相同的值。下同2
neighbor_history	将以neighbor为参数返回的结果存入历史记录服务器，并返回 query_key 和WebEnv。同1
acheck	返回给定UID的所有可能链接方式。如不设置db相当于选中所有。
ncheck	判断同一个数据库中是否存在与给定的UID相关的链接。同2，忽略db设置
lcheck	判断给定的UID是否存在链出链接。同2，忽略db设置
llinks	列出给定UID的所有非图书馆链出链接及对应属性。同2，忽略db设置
llinkslib	列出给定UID的所有链出链接及对应属性，包含图书馆链接。同2，忽略db设置
prlinks	列出给定UID的首选链出链接及对应属性，在设置retmode=ref情况下直接跳转到链接网页。同2，忽略db设置

• EGQuery示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/egquery.fcgi?term=asthma

示例1返回所有数据库中含有关键词asthma的条目数

注：EGQuery为全局查询，和在Entrez中选择所有数据库查询的结果相同。

• ESpell示例

示例1：http://eutils.ncbi.nlm.nih.gov/entrez/eutils/espell.fcgi?db=pubmed&term=asthmaa+OR+alergies

示例1返回对三个关键词的拼写建议，asthmaa被替换为asthma，OR为逻辑词不进行替换，alergies被替换为allergies。

注：ESpell为拼写建议工具，会根据关键词的相似性进行建议，方便关键词的纠错和相关关键词的推荐。

部分通用参数解释

db：查询的数据库名称。和Entrez下拉菜单中显示的名称不一样，所支持的所有值可通过EInfo(http://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi)查看；

term：查询的关键词。和Entrez查询相似，可使用逻辑操作词AND，OR，NOT以及[acession]、[organism]等以字段限定词等（具体可参见Entrez Help），但是中间的空格要以“+”替代，其他特殊符号要转换为URL编码（如引号“编码为%22；井号#编码为%23）。

WebEnv：历史记录环境编号。 ESearch的usehistory=y参数、EPost、ELink的cmd=neighbor_history参数都会产生一个WebEnv。后续操作传入次参数将大大减少查询工作量。

query_key：历史记录环境下的查询编号。第一次生成WebEnv的结果的query_key为1，在此WebEnv环境下的下一个操作结果的query_key为2，后续操作依次递增。

retstart：返回结果在查询结果中的起始位置。默认为0，配合retmax实现分页显示。

retmax：返回结果条目数最大值。默认为20。

rettype：返回数据类型。不同的工具有不同的可选值。ESearch的可选类型为uilist（默认）和count（只返回查询结果数目），EFetch可参加表2。

retmode：返回数据方式。详见表2。

datetype：限定日期的类型。限定reldate, mindate, maxdate的日期类型，不同的数据库有不同的可选值，常见的为mdat(modification date)、pdat(publication
date)、edat (Entrez date)。

reldate：相对于当前时间的天数。返回过去多少天内的数据。

mindate, maxdate：时间间隔。返回由最小日期和最大日期限定的时间间隔中的数据，必须同时使用，格式为YYYY/MM/DD，或者YYYY, YYYY/MM。

其他参数解释

field：ESearch中term的限定字段。如[accession]、[title]等，设置此参数后，term中的所有关键词将只查询指定字段。

version：指定所使用Esummary的版本号。

strand：指定EFetch中DNA链的类型，正义为1，反义为2。

seq_start：指定EFetch中返回序列的起始位点。

seq_stop：指定EFetch中返回序列的终止位点。

complexity：指定EFetch中返回数据的内容。许多序列数据和其他数据存储在一起，组成一个大的数据结构或BLOB（二进制大对象）。指定该参数可选择返回哪些数据内容。详见表4。

linkname：限定ELink中限制返回的链接类型，如gene_snp_genegenotype只返回所有链接中genegenotype子类。

holding：限定ELink中链出链接的提供商。

表4. EFetch中complexity值与返回的数据内容

Value of complexity	Data returned for each requested GI
0	entire blob
1	bioseq
2	minimal bioseq-set
3	minimal nuc-prot
4	minimal pub-set

结语

这里根据前一段时间使用和学习Eutils的经历，参考《Entrez Programming Utilities Help》一书对Eutils的用法做了初步的总结，不可避免有错误，欢迎指正。

本文未涉及返回结果处理和编程部分，后面考虑是否写一下相关文章。

参考链接

《Entrez Programming Utilities Help》: http://www.ncbi.nlm.nih.gov/books/NBK25501/

《Entrez Help》: http://www.ncbi.nlm.nih.gov/books/NBK3837/