NCBI GEO Database Access in Python: Download and Parse GSE Datasets
Use Claude Code to search NCBI GEO, download GSE series with GEOparse, map probe IDs to genes, and build analysis-ready expression matrices from microarray and RNA-seq studies.
A paper reports a key gene expression finding but doesn't share processed data — just a GEO accession number. Downloading the right GSE dataset, parsing SOFT/Matrix files, and extracting the expression values you need requires navigating GEO's structure. Programmatic access lets you search, download, and parse GEO data directly into your analysis.
Who it's for: bioinformaticians downloading and reanalyzing public gene expression datasets, transcriptomics researchers building meta-analyses across multiple GEO studies, graduate students accessing microarray and RNA-seq data for their projects, computational biologists benchmarking methods on public expression datasets, lab scientists retrieving expression data to validate their own results
Example
"Download and parse gene expression data from 5 GEO datasets for our meta-analysis" → GEO data retrieval: dataset search and metadata extraction, SOFT/Matrix file parsing for expression values, sample annotation mapping, cross-dataset gene ID harmonization, and a combined expression matrix ready for differential expression or meta-analysis
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
# GEO Database
## Overview
The Gene Expression Omnibus (GEO) is NCBI's public repository for high-throughput gene expression and functional genomics data. GEO contains over 264,000 studies with more than 8 million samples from both array-based and sequence-based experiments.
## When to Use This Skill
This skill should be used when searching for gene expression datasets, retrieving experimental data, downloading raw and processed files, querying expression profiles, or integrating GEO data into computational analysis workflows.
## Core Capabilities
Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Teaches Claude Code how to work with the Gene Expression Omnibus (GEO), NCBI's public archive of gene expression and functional genomics studies. With the template loaded, you can hand Claude an accession number from a paper ("GSE12345") or a research question ("breast cancer tamoxifen-resistance studies on Affymetrix arrays") and get back a parsed, annotated expression matrix in pandas, plus the sample metadata you need to define your comparison groups.
The template is a detailed code reference covering GEOparse, Biopython's Entrez E-utilities, direct FTP downloads, differential expression and batch processing. Expand it above to read the full code examples. This page covers how to use it well.
Quick Start
Step 1: Create a Project Folder
mkdir -p ~/Projects/geo-database
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ~/Projects/geo-database/
Step 3: Install the Libraries and Start Claude Code
uv pip install GEOparse biopython pandas numpy scipy statsmodels scikit-learn matplotlib seaborn
cd ~/Projects/geo-database
claude
Before your first request, tell Claude your email address. NCBI requires one for programmatic access, and the template sets it in Entrez.email. If you'll be querying a lot, add a free NCBI API key too: it raises the limit from 3 to 10 requests per second.
The Four Accession Types, in Practice
| Prefix | What it is | When you'll use it |
|---|---|---|
| GSE | A Series: one study, all its samples | Almost always your starting point; papers cite GSE numbers |
| GSM | A single Sample | Checking one sample's metadata or processing notes |
| GPL | A Platform: the array or sequencer | Mapping probe IDs to gene symbols for microarray data |
| GDS | A curated DataSet | Older studies only; most recent work exists only as a GSE |
Microarray vs. RNA-seq: Where the Numbers Actually Are
This is the most common source of confusion, and it decides which part of the template you need.
- Microarray studies usually have a series matrix file with one value per probe per sample. GEOparse loads it straight into a DataFrame, but the rows are probe IDs, not genes. Ask Claude to join against the GPL annotation table to get gene symbols, and to decide how to collapse multiple probes per gene (mean, or the highest-variance probe).
- RNA-seq studies often have an empty or minimal series matrix. The counts live in supplementary files attached to the series, in whatever format the submitters chose. For many human and mouse studies, GEO also provides NCBI-generated raw count matrices on the series page, which are more consistent across studies than submitter files.
A good first prompt is: "Inspect GSE12345 and tell me where the expression values are, what units they're in, and whether they look log-transformed, before downloading anything large."
Checks Before You Trust a Dataset
- Is it already log-transformed? Values mostly between 0 and 16 suggest log2. Values in the thousands suggest raw or linear-scale data. Log-transforming twice silently destroys a differential expression result.
- Are the sample groups where you think they are? Group labels sit in free-text fields such as
characteristics_ch1andsource_name_ch1, formatted differently in every study. Have Claude print the unique values and confirm the treated/control split with you before running statistics. - How big is it? Supplementary archives for large studies run to gigabytes. Ask for file sizes first.
Combining Several Studies
The template's batch-processing section loops over a list of GSE IDs. For a meta-analysis that's only the first step:
- Harmonize identifiers across platforms (probe IDs → gene symbols, or Ensembl IDs for RNA-seq).
- Keep only genes measured in every study.
- Treat each study as a batch. Combining raw values from different labs and platforms mostly measures the lab, not the biology. Run differential expression per study and combine effect sizes, or use a batch-correction method and say which one in your methods.
Cite What You Use
GEO data is free for research use, but cite both the original study for every series you analyze and the GEO database itself. Ask Claude to compile the citation for each GSE from its metadata as part of the pipeline, so the references are ready when you write up.
Related Playbooks
- Single-Cell RNA-seq QC — quality control for single-cell data downloaded from GEO supplementary files
- Dataset Explorer — profile a downloaded expression matrix for missing values, outliers and distribution shape
- Research Synthesizer — pull together findings from the papers behind the datasets you analyze