easy-entrez

Python REST API for Entrez E-Utilities，旨在易于使用和可靠。

Easy-entrez

• 通过简单的Pythonic API简化了常见任务，
• 已类型化，并与mypy集成良好，
• 在Windows、Mac和Linux上经过测试，支持Python 3.7、3.8、3.9、3.10和3.11，
• 范围有限，允许专注于核心代码的可靠性，
• 不使用有状态的API，因为它在entrezpy的替代示例中已被证明是易出错的。

示例

from easy_entrez import EntrezAPI

entrez_api = EntrezAPI(
    'your-tool-name',
    'e@mail.com',
    # optional
    return_type='json'
)

# find up to 10 000 results for cancer in human
result = entrez_api.search('cancer AND human[organism]', max_results=10_000)

# data will be populated with JSON or XML (depending on the `return_type` value)
result.data

请参阅示例笔记本和文档了解更多。

对于现实世界的示例（即用于这篇论文），请参阅多组学领域现状存储库中的笔记本multi-omics-state-of-the-field。

从dbSNP获取变异数据

获取rs6311的SNP记录

rs6311 = entrez_api.fetch(['rs6311'], max_results=1, database='snp').data[0]
rs6311

显示结果

from easy_entrez.parsing import xml_to_string

print(xml_to_string(rs6311))

查找rs6311的基因名称

namespaces = {'ns0': 'https://www.ncbi.nlm.nih.gov/SNP/docsum'}
genes = [
    name.text
    for name in rs6311.findall('.//ns0:GENE_E/ns0:NAME', namespaces)
]
print(genes)

['HTR2A']

一次性获取多个变异数据

result = entrez_api.fetch(['rs6311', 'rs662138'], max_results=10, database='snp')
gene_names = {
    'rs' + document_summary.get('uid'): [
        element.text
        for element in document_summary.findall('.//ns0:GENE_E/ns0:NAME', namespaces)
    ]
    for document_summary in result.data
}
print(gene_names)

{'rs6311': ['HTR2A'], 'rs662138': ['SLC22A1']}

从SNP rsID号获取染色体位置

from pandas import DataFrame

result = entrez_api.fetch(['rs6311', 'rs662138'], max_results=10, database='snp')

variant_positions = DataFrame([
    {
        'id': 'rs' + document_summary.get('uid'),
        'chromosome': chromosome,
        'position': position
    }
    for document_summary in result.data
    for chrom_and_position in document_summary.findall('.//ns0:CHRPOS', namespaces)
    for chromosome, position in [chrom_and_position.text.split(':')]
])

variant_positions

	id	染色体	位置
0	rs6311	13	46897343
1	rs662138	6	160143444

将全变异/突变数据转换为表格格式

解析工具可以快速提取数据到包含pandas DataFrame的VariantSet对象，其中包含坐标和替代等位基因频率

from easy_entrez.parsing import parse_dbsnp_variants

variants = parse_dbsnp_variants(result)
variants

<包含2个变异数据的VariantSet>

获取坐标

variants.coordinates

rs_id	ref	alts	chrom	pos	chrom_prev	pos_prev	后果
rs6311	C	A,T	13	46897343	13	47471478	upstream_transcript_variant,intron_variant,genic_upstream_transcript_variant
rs662138	C	G	6	160143444	6	160564476	intron_variant

对于频率

variants.alt_frequencies.head(5)  # using head to only display first 5 for brevity

	rs_id	等位基因	source_frequency	total_count	研究	count
0	rs6311	T	0.44349	2221	1000Genomes	984.991
1	rs6311	T	0.411261	1585	ALSPAC	651.849
2	rs6311	T	0.331696	1486	Estonian	492.9
3	rs6311	T	0.35	14	GENOME_DK	4.9
4	rs6311	T	0.402529	56309	GnomAD	22666

从染色体位置获取SNP rs ID号

您可以直接使用查询字符串

results = entrez_api.search(
    '13[CHROMOSOME] AND human[ORGANISM] AND 31873085[POSITION]',
    database='snp',
    max_results=10
)
print(results.data['esearchresult']['idlist'])

['59296319', '17076752', '7336701', '4']

或者传递一个字典（不验证参数，使用AND连接词）

results = entrez_api.search(
    dict(chromosome=13, organism='human', position=31873085),
    database='snp',
    max_results=10
)
print(results.data['esearchresult']['idlist'])

['59296319', '17076752', '7336701', '4']

基准位置应使用最新的基因组组装（写作时的GRCh38）；您可以通过将POSITION替换为POSITION_GRCH37来使用先前组装的坐标。有关SNP数据库接受的参数的更多信息，请参阅NCBI网站上的entrez帮助页面。

获取给定范围内变异数据的氨基酸变化信息

首先，我们在给定区域内搜索dbSNP rs标识符

dbsnp_ids = (
    entrez_api
    .search(
        '12[CHROMOSOME] AND human[ORGANISM] AND 21178600:21178720[POSITION]',
        database='snp',
        max_results=100
    )
    .data
    ['esearchresult']
    ['idlist']
)

然后获取标识符的变异数据

variant_data = entrez_api.fetch(
    ['rs' + rs_id for rs_id in dbsnp_ids],
    max_results=10,
    database='snp'
)

然后解析数据，从摘要中提取HGVS

from easy_entrez.parsing import parse_dbsnp_variants
from pandas import Series


def select_protein_hgvs(items):
    return [
        [sequence, hgvs]
        for entry in items
        for sequence, hgvs in [entry.split(':')]
        if hgvs.startswith('p.')
    ]


protein_hgvs = (
    parse_dbsnp_variants(variant_data)
    .summary
    .HGVS
    .apply(select_protein_hgvs)
    .explode()
    .dropna()
    .apply(Series)
    .rename(columns={0: 'sequence', 1: 'hgvs'})
)
protein_hgvs.head()

rs_id	序列	hgvs
rs1940853486	NP_006437.3	p.Gly203Ter
rs1940853414	NP_006437.3	p.Glu202Gly
rs1940853378	NP_006437.3	p.Glu202Lys
rs1940853299	NP_006437.3	p.Lys201Thr
rs1940852987	NP_006437.3	p.Asp198Glu

获取超过10,000个条目的数据

使用in_batches_of方法获取超过10k的条目（例如variant_ids）

snps_result = (
    entrez.api
    .in_batches_of(1_000)
    .fetch(variant_ids, max_results=5_000, database='snp')
)

结果是包含每个批次使用的标识符作为键的字典，值表示结果（因为Entrez API并不总是返回标识符）。您可以直接在字典上使用parse_dbsnp_variants。

从DOI获取PubMed ID

当在GWAS目录中搜索时，需要PMID而不是DOI。您可以使用以下方法将其转换为另一个

def doi_term(doi: str) -> str:
    """Prepare DOI for PubMed search"""
    doi = (
        doi
        .replace('http://', 'https://')
        .replace('https://doi.org/', '')
    )
    return f'"{doi}"[Publisher ID]'


result = entrez_api.search(
    doi_term('https://doi.org/10.3389/fcell.2021.626821'),
    database='pubmed',
    max_results=1
)
result.data['esearchresult']['idlist']

['33834021']

安装

需要Python 3.6+。使用以下命令安装

pip install easy-entrez

如果您想启用（可选，基于tqdm）进度条，请使用

pip install easy-entrez[with_progress_bars]

如果您想启用（可选，基于pandas）解析工具，请使用

pip install easy-entrez[with_parsing_utils]

替代方案

您可能想尝试

• biopython.Entrez - biopython是一个重依赖项，但如果您已经使用它，可能是一个不错的选择
• pubmedpy - 提供了有趣的解析响应的工具
• entrez - 看起来具有类似的作用范围，但API相当不同
• entrezpy - 这个包在我的测试中效果不佳（因此这个包），但可能已经改进