Version Compatibility

Reference examples tested with: BioPython 1.83+, Entrez Direct 21.0+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show biopython then help(Bio.Entrez.elink) to check signatures
• CLI: elink -version then elink -help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Entrez Link

"Find records linked to this record in another NCBI database" -> ELink walks the curated, weekly-maintained link tables between Entrez databases. A link is an asserted relationship (e.g. "this PubMed article describes this nucleotide sequence"), not a similarity hit.

ELink is the navigation layer of Entrez. The decision that matters most is which linkname to use — not which databases. A single (dbfrom, db) pair can have a dozen linkname variants distinguishing curation level, evidence type, and direction. Picking the wrong one is the difference between 5 high-confidence matches and 500 noisy automated assertions.

• Python: Entrez.elink(dbfrom=..., db=..., id=..., linkname=...) (BioPython)
• CLI: elink -db pubmed -target gene -name pubmedgenerif (Entrez Direct)
• R: entrez_link(dbfrom=..., db=..., id=...) (rentrez)

Required Setup

from Bio import Entrez
Entrez.email = '[email protected]'
Entrez.api_key = 'optional_api_key'  # raises rate to 10 req/sec

The linkname decision (most important)

For most (dbfrom, db) pairs NCBI exposes multiple link tables. The qualifiers in the name encode the curation level and the evidence source. Choose deliberately.

gene -> protein (representative example)

pubmed -> gene

nucleotide -> protein

Discover what link names exist for a pair

h = Entrez.elink(dbfrom='gene', db='protein', id='672', cmd='acheck')
record = Entrez.read(h); h.close()
for ls in record[0]['IdCheckList']['IdLinkSet'][0]['LinkInfo']:
    print(f'{ls["Name"]}  -> {ls["DbTo"]} | {ls["MenuTag"]} ({ls["HtmlTag"]})')

cmd='acheck' is the only authoritative way to enumerate available linknames — they change with each NCBI release.

Decision table: which cmd for which goal

The neighborhistory cmd is essential when source id count exceeds ~200 — past that, the URL-length limit makes the comma-joined form fail. With neighborhistory ELink puts results on the history server and returns WebEnv/QueryKey for downstream pickup.

Asymmetric link warning

ELink relationships are not guaranteed symmetric. pubmedgene and genepubmed may return different sets because:

• Direction-dependent curation: gene-to-PubMed is curated by NCBI staff (GeneRIF); PubMed-to-gene includes text-mining.
• Cutoffs: some link tables truncate at N best links in one direction but not the other.
• Index lag asymmetry: when one db updates faster than the other.

If round-trip consistency matters (e.g. "every gene mentioned in this paper, then every paper mentioning each gene"), expect the round-trip set to be larger than the input — and never assume A -> B -> A returns the original ID alone.

Per-database link catalog (curated subset)

gene

nuccore / nucleotide

protein

pubmed

bioproject

Code patterns

Single source -> single target

Goal: Get RefSeq proteins for a single gene.

Approach: ELink with explicit linkname to restrict to curated set.

Reference (BioPython 1.83+):

def gene_to_refseq_proteins(gene_id):
    h = Entrez.elink(dbfrom='gene', db='protein', id=gene_id, linkname='gene_protein_refseq')
    r = Entrez.read(h); h.close()
    if not r[0]['LinkSetDb']:
        return []
    return [link['Id'] for link in r[0]['LinkSetDb'][0]['Link']]

print(gene_to_refseq_proteins('672'))  # BRCA1

Batch source -> target (small batch)

Goal: Get linked proteins for a list of <200 gene IDs in one call.

Approach: Comma-join IDs; one linkset per input in the response.

Reference (BioPython 1.83+):

def batch_gene_protein(gene_ids):
    h = Entrez.elink(dbfrom='gene', db='protein', id=','.join(gene_ids), linkname='gene_protein_refseq')
    r = Entrez.read(h); h.close()
    out = {}
    for linkset in r:
        src = linkset['IdList'][0]
        out[src] = [link['Id'] for link in linkset['LinkSetDb'][0]['Link']] if linkset['LinkSetDb'] else []
    return out

Large batch via history server

Goal: Link 5,000 gene IDs to proteins without hitting URL-length limits.

Approach: EPost the IDs first (chunked at 200), then ELink with cmd='neighbor_history' referencing the WebEnv. Downstream EFetch picks up linked IDs from the history server.

Reference (BioPython 1.83+):

def post_then_link(gene_ids, target='protein', linkname='gene_protein_refseq'):
    # EPost in chunks of 200
    webenv = None
    for i in range(0, len(gene_ids), 200):
        chunk = gene_ids[i:i+200]
        kwargs = {'db': 'gene', 'id': ','.join(chunk)}
        if webenv:
            kwargs['WebEnv'] = webenv
        h = Entrez.epost(**kwargs)
        r = Entrez.read(h); h.close()
        webenv = r['WebEnv']
        query_key = r['QueryKey']
        time.sleep(0.1 if Entrez.api_key else 0.34)

    # Link with neighbor_history
    h = Entrez.elink(dbfrom='gene', db=target, linkname=linkname,
                     cmd='neighbor_history', WebEnv=webenv, query_key=query_key)
    r = Entrez.read(h); h.close()
    # WebEnv is at the top level of the response; QueryKey is per-LinkSetDbHistory entry.
    return r[0]['WebEnv'], r[0]['LinkSetDbHistory'][0]['QueryKey']

we, qk = post_then_link(['672', '675', '7157'] * 1000)
# Downstream: Entrez.efetch(db='protein', WebEnv=we, query_key=qk, retstart=..., retmax=500)

Discover all available links

Goal: Before writing a pipeline, enumerate what link tables NCBI exposes for a (dbfrom, source-id) pair.

Approach: cmd='acheck' returns the full LinkInfo list per source.

Reference (BioPython 1.83+):

def list_link_names(dbfrom, id):
    h = Entrez.elink(dbfrom=dbfrom, id=id, cmd='acheck')
    r = Entrez.read(h); h.close()
    info = r[0]['IdCheckList']['IdLinkSet'][0]['LinkInfo']
    return [(i['Name'], i['DbTo'], i['MenuTag']) for i in info]

for name, target, label in list_link_names('gene', '672'):
    print(f'{name:<40} -> {target:<15} ({label})')

Chain links (gene -> protein -> structure)

def gene_to_structures(gene_id):
    h = Entrez.elink(dbfrom='gene', db='protein', id=gene_id, linkname='gene_protein_refseq')
    r = Entrez.read(h); h.close()
    if not r[0]['LinkSetDb']:
        return []
    prot_ids = [l['Id'] for l in r[0]['LinkSetDb'][0]['Link'][:10]]
    time.sleep(0.1 if Entrez.api_key else 0.34)
    h = Entrez.elink(dbfrom='protein', db='structure', id=','.join(prot_ids))
    r = Entrez.read(h); h.close()
    out = []
    for ls in r:
        if ls['LinkSetDb']:
            out.extend(l['Id'] for l in ls['LinkSetDb'][0]['Link'])
    return out

Get neighbor_score for related PubMed articles

def related_pubmed(pmid, top=10):
    h = Entrez.elink(dbfrom='pubmed', db='pubmed', id=pmid,
                     linkname='pubmed_pubmed', cmd='neighbor_score')
    r = Entrez.read(h); h.close()
    if not r[0]['LinkSetDb']:
        return []
    return [(l['Id'], int(l['Score'])) for l in r[0]['LinkSetDb'][0]['Link'][:top]]

BioProject -> SRA runs

For SRA discovery, pysradb.SRAweb().sra_metadata(prjna, detailed=True) (see sra-data) is the higher-fidelity path — returns SRR accessions directly with run-level metadata in one call. Use ELink only when staying inside Bio.Entrez:

def bioproject_to_sra(prjna):
    # Convert PRJNA to UID first
    h = Entrez.esearch(db='bioproject', term=f'{prjna}[BioProject]')
    r = Entrez.read(h); h.close()
    if not r['IdList']:
        return []
    bp_uid = r['IdList'][0]
    time.sleep(0.1 if Entrez.api_key else 0.34)
    # Link to SRA
    h = Entrez.elink(dbfrom='bioproject', db='sra', id=bp_uid)
    r = Entrez.read(h); h.close()
    return [l['Id'] for l in r[0]['LinkSetDb'][0]['Link']] if r[0]['LinkSetDb'] else []

Failure modes

Wrong linkname gives wrong order of magnitude

• Trigger: Using geneprotein when geneprotein_refseq was intended.
• Mechanism: geneprotein includes all automated and predicted entries (XP* RefSeq plus all GenBank submissions).
• Symptom: 500 proteins returned per gene instead of the expected 1-5 canonical isoforms.
• Fix: Pick the curated linkname; verify counts on a known gene.

Empty LinkSetDb on valid input

• Trigger: Gene with no linked records in the requested target.
• Mechanism: record[0]['LinkSetDb'] is an empty list, not raising an error.
• Symptom: KeyError if code assumes record[0]['LinkSetDb'][0] always exists.
• Fix: Always guard if not record[0]['LinkSetDb']: return [].

Asymmetric round-trip

• Trigger: Pipeline does genesforpaper(pmid) -> papersforeach_gene -> set of PMIDs.
• Mechanism: pubmedgene (text-mined + curated) is larger than genepubmed (curated only); the round-trip set is not closed.
• Symptom: Original PMID may not appear in the round-trip set; new PMIDs do.
• Fix: Document the directional asymmetry; use the more-curated linkname (*_rif variants) when fidelity matters.

URL length limit on large batches

• Trigger: Comma-joined id= with 200+ IDs.
• Mechanism: HTTP GET URL exceeds NCBI's parsing limit (~2000 chars).
• Symptom: HTTP 414 URI Too Long, or silent truncation.
• Fix: EPost the IDs first, then ELink with cmd='neighbor_history'.

One linkset per input ID, indexing confusion

• Trigger: Sending 5 IDs, then accessing record[0]['LinkSetDb'][0]['Link'] expecting the union.
• Mechanism: ELink returns one LinkSet per input UID, indexed by position.
• Symptom: Only the first input's links are processed; rest are dropped.
• Fix: Iterate for linkset in record: and map by linkset['IdList'][0].

Mismatched dbfrom and id namespace

• Trigger: Passing a PMID into dbfrom='nucleotide'.
• Mechanism: ELink returns no error — it just looks up the PMID as a nucleotide UID, finds nothing.
• Symptom: Empty LinkSetDb on a "valid" ID.
• Fix: Validate that the ID matches the source db namespace (PMIDs are db=pubmed, GeneIDs are db=gene).

Common errors

References

• Sayers EW et al. (2024) Database resources of the National Center for Biotechnology Information in 2024. Nucleic Acids Res 52:D33-D43.
• Kans J. (2024) Entrez Direct: E-utilities on the Unix Command Line. NCBI Bookshelf NBK179288.
• NCBI. ELink help. NBK25499.

Related Skills

• entrez-search - Resolve UIDs before linking
• entrez-fetch - Retrieve linked records' content
• batch-downloads - History-server retrieval after ELink with neighbor_history
• geo-data - Specialized gds <-> pubmed/bioproject links (gds->sra ELink unreliable; use pysradb)
• ncbi-datasets-cli - Modern alternative for gene/genome cross-reference queries