NCBI RefSeq (Reference Sequence collection): sample notebook

A worked notebook for NCBI RefSeq (Reference Sequence collection), with 5 code cells and the output each one printed. On Scigantic it opens in a hosted JupyterLab with the dataset already mounted, so nothing is downloaded first.

Provider
NCBI / NLM / NIH
License
NCBI Public Domain (US Government work)
Stored at
ftp.ncbi.nlm.nih.gov/refseq
Access
Free and public. No account with the data provider is needed.
DOI
10.1093/nar/gkv1189

The notebook

NCBI RefSeq — fetch reference sequences by accession or gene

RefSeq is NCBI's curated, non-redundant reference collection — the canonical source for nucleotide and protein identifiers (NM_, NP_, XM_, XP_, NR_, XR_).

How this archive works: RefSeq is served from NCBI and accessed here through NCBI's E-utilities API via Bio.Entrez (already installed) — *not* a file mount. This is NCBI's sanctioned, rate-limit-friendly path: ask for the records you need by accession or gene and get real data back, instead of pulling the multi-tens-of-GB FTP tree.

Run the cells below to fetch a sequence, resolve a gene symbol, and pull gene metadata.

import os
from Bio import Entrez

# NCBI etiquette: identify yourself. The optional API key (injected by the
# spawn hook from the scigantic-ncbi-api-key Secret) raises the E-utilities
# rate limit from 3 to 10 requests/second. Everything works without it.
Entrez.email = os.environ.get("NCBI_EMAIL", "support@scigantic.com")
_key = os.environ.get("NCBI_API_KEY")
if _key:
    Entrez.api_key = _key
    print("NCBI API key detected — rate limit 10 req/s.")
else:
    print("No NCBI API key — anonymous rate limit 3 req/s (fine for this notebook).")

1. Fetch a RefSeq record by accession

NM_000546 is the human TP53 mRNA (transcript variant 1). efetch returns the FASTA, and Biopython parses it into a SeqRecord.

from io import StringIO
from Bio import SeqIO

accession = "NM_000546"  # human TP53 mRNA, transcript variant 1
with Entrez.efetch(db="nuccore", id=accession, rettype="fasta", retmode="text") as handle:
    record = SeqIO.read(handle, "fasta")

print("ID:         ", record.id)
print("Description:", record.description)
print("Length:     ", len(record.seq), "nt")
print("First 60 nt:", record.seq[:60])

2. Resolve a gene symbol → RefSeq mRNA accessions

Search nuccore with refseq[filter] to get only curated RefSeq records for a gene, then resolve each UID to its accession.version.

gene = "BRCA1"
query = f"{gene}[gene] AND Homo sapiens[orgn] AND refseq[filter] AND biomol_mrna[prop]"
with Entrez.esearch(db="nuccore", term=query, retmax=5) as handle:
    search = Entrez.read(handle)

print(f"{search['Count']} RefSeq mRNA record(s) for {gene}; resolving accessions:")
for uid in search["IdList"]:
    with Entrez.efetch(db="nuccore", id=uid, rettype="acc", retmode="text") as h:
        print("  ", h.read().strip())

3. Gene-level metadata

esummary on the gene database gives the official name, genomic location, and the curated RefSeq summary.

with Entrez.esearch(db="gene", term="BRCA1[sym] AND Homo sapiens[orgn]") as handle:
    gene_id = Entrez.read(handle)["IdList"][0]
with Entrez.esummary(db="gene", id=gene_id) as handle:
    doc = Entrez.read(handle)["DocumentSummarySet"]["DocumentSummary"][0]

print("Gene ID:    ", gene_id)
print("Name:       ", doc.get("Description"))
print("Chromosome: ", doc.get("Chromosome"), "| Map:", doc.get("MapLocation"))
print("Summary:    ", (doc.get("Summary") or "")[:280], "...")

4. Whole gene/genome packages — the datasets CLI

For *packages* of sequence + annotation (not single records), NCBI's datasets CLI is the sanctioned bulk tool (installed in this image). It pulls a zip by accession or taxon — no FTP, no key needed.

# Summary of the human TP53 gene package (metadata only; add `download` to pull data).
!datasets summary gene symbol TP53 --taxon human 2>/dev/null | head -c 600 || echo 'datasets CLI not in this image yet'

Where to go next

RefSeq records are public domain (US Government work).

Run it

Open this notebook to run it, see the dataset page for the full description, or browse the full catalog.