Written and maintained by CASRAI Editorial Board
Published
On this page
GEOquery is an open-source Bioconductor R package that automates downloading, parsing, and loading functional genomics datasets from the National Center for Biotechnology Information (NCBI) Gene Expression Omnibus (GEO) repository directly into standard R data structures. Developed by Sean Davis and maintained within the Bioconductor project, GEOquery bridges public repository archives and downstream statistical tools, converting complex plain-text matrix files into ready-to-analyze ExpressionSet and SummarizedExperiment containers without requiring manual file downloads.
What GEOquery is used for in research
In modern biomedical and computational biology research, accessing public transcriptomic and genomic data is central to hypothesis testing, cross-study validation, biomarker discovery, and meta-analyses. The National Center for Biotechnology Information operates the Gene Expression Omnibus (GEO), the world’s largest public archive of microarray, RNA sequencing (RNA-seq), ChIP-seq, and single-cell genomics experiments. However, manually retrieving datasets through web browsers presents significant computational bottlenecks. Traditional web downloads force investigators to navigate diverse file structures, decompress archive folders, parse header metadata, and align phenotypic traits with expression matrices using custom parsing scripts.
GEOquery resolves these data ingestion bottlenecks by providing an automated programmatic interface in R. By calling simple accession queries, researchers can download and parse four primary classes of NCBI GEO records:
- GEO Series (GSE): Complete experimental studies comprising groups of related samples analyzed under a single study design or publication.
- GEO Samples (GSM): Individual assay records describing single biological samples, hybridizations, or sequencing runs, including treatment conditions and raw intensity data.
- GEO Platforms (GPL): Comprehensive array definitions or sequencing annotations containing probe identifiers, GenBank accessions, gene symbols, and genomic coordinates.
- GEO Datasets (GDS): Curated collections of biologically comparable samples assembled by NCBI staff from submitted series, normalized to common distribution profiles.
Beyond simple downloading, GEOquery converts raw text archives directly into Bioconductor’s foundational S4 data containers, primarily the ExpressionSet object from the Biobase package and modern SummarizedExperiment objects. This architectural integration means expression values, sample phenotypes, and probe annotations remain strictly synchronized throughout downstream exploratory data analysis. The data structures produced by GEOquery feed directly into differential expression workflows using packages such as limma, DESeq2, and edgeR, as well as downstream visualization tools for generating heatmaps and volcano plots in RNA-seq.
Adopting GEOquery supports computational reproducibility in scientific publishing. Rather than distributing bulky, multi-gigabyte flat files alongside analysis code, researchers can write compact R scripts containing only the GEO accession number and processing parameters. Any analyst running the script worldwide can retrieve identical datasets directly from the upstream repository, adhering to global FAIR data principles for findability, accessibility, interoperability, and reusability.
How to install or access GEOquery
GEOquery is distributed as an official Bioconductor package. To guarantee dependency resolution and ensure binary compatibility with foundational packages such as Biobase, readr, and httr, it must be installed using Bioconductor’s dedicated package manager, BiocManager, rather than standard CRAN mechanisms. For researchers unfamiliar with Bioconductor repository configuration, Casrai maintains an overview of how to install R packages across CRAN, Bioconductor, and GitHub repositories.
To install the stable release version of GEOquery from Bioconductor, execute the following commands in an active R console (version 4.0 or higher):
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("GEOquery")
For computational environments that require the latest development features, bug fixes, or experimental enhancements, Bioconductor permits direct installation from the developer’s GitHub repository. Using BiocManager ensures that all necessary Bioconductor dependencies are fetched alongside the GitHub source tree:
BiocManager::install("seandavi/GEOquery")
Once installation finishes, load the package into your R session and verify the installed release version:
library(GEOquery)
packageVersion("GEOquery")
GEOquery relies on system libraries for network connectivity and compression, including libcurl, zlib, and openssl. On Debian and Ubuntu Linux servers, administrators should verify that libcurl4-openssl-dev and libxml2-dev are installed at the system level before initiating the Bioconductor build process. In high-performance computing (HPC) environments where compute nodes lack direct internet access, researchers must either configure an outgoing HTTP proxy via Sys.setenv(http_proxy = "...") or download files on a transfer node prior to running batch scripts.
How to download and parse GEO datasets step by step
Retrieving and preparing functional genomics data with GEOquery follows a systematic workflow. The following step-by-step walkthrough demonstrates how to download, inspect, and extract assay matrices from a public GEO Series accession.
Step 1: Identify the target GEO accession number
Locate the study accession number from the published literature or the NCBI GEO web portal. For this walkthrough, consider accession GSE42872, an established gene expression profiling experiment performed on human cell lines. GEO Series accessions always carry the prefix GSE followed by numeric digits.
Step 2: Download the series matrix using getGEO
The primary workhorse function of GEOquery is getGEO(). By default, getGEO() downloads pre-parsed Series Matrix files, which are compact, tab-delimited text representations containing both expression matrices and experimental metadata. Specify a dedicated destination directory to cache downloaded files locally:
# Define target accession and destination directory
accession_id <- "GSE42872"
dest_folder <- tempdir()
# Query and retrieve dataset
gse_list <- getGEO(GEO = accession_id,
GSEMatrix = TRUE,
AnnotGPL = TRUE,
destdir = dest_folder)
Setting GSEMatrix = TRUE instructs the parser to retrieve Series Matrix files rather than the raw, verbose SOFT file. Setting AnnotGPL = TRUE directs GEOquery to fetch NCBI-curated platform annotation files, which enrich the feature data with standardized gene symbols, Entrez IDs, and gene descriptions.
Step 3: Extract the ExpressionSet object
Because some experimental series incorporate multiple microarray platforms (e.g., matching miRNA and mRNA arrays) or sequencing designs, getGEO() always returns a standard R list of ExpressionSet objects, where each list element corresponds to a specific platform. Inspect the length of the list and extract the primary dataset:
# Check how many platforms are present in this series
length(gse_list)
# Extract the primary ExpressionSet
eset <- gse_list[[1]]
print(eset)
Step 4: Extract the quantitative expression matrix
The core quantitative measurement matrix is extracted using the exprs() method from the Biobase package. This matrix contains numeric values where rows represent probes or genes and columns represent individual biological samples:
# Extract numeric expression values
expression_matrix <- exprs(eset)
# Inspect matrix dimensions and sample names
dim(expression_matrix)
head(expression_matrix[, 1:3])
Step 5: Extract clinical and phenotypic metadata
Phenotypic information, sample annotations, treatment conditions, and batch variables are stored in the object’s phenoData slot. Retrieve this metadata as a standard R data.frame using pData():
# Extract sample metadata table
sample_metadata <- pData(eset)
# Review available metadata columns
colnames(sample_metadata)
# Inspect sample titles and experimental groups
sample_metadata[, c("title", "geo_accession", "source_name_ch1")]
Step 6: Retrieve probe-to-gene feature annotations
To interpret numeric probe intensities in terms of biological pathways, extract the feature annotation table using fData():
# Extract probe and gene annotation data
feature_annotations <- fData(eset)
# View mapped gene symbols and descriptions
head(feature_annotations[, c("ID", "Gene symbol", "Gene title", "Entrez Gene")])
Step 7: Download raw supplementary files when needed
While Series Matrix files provide normalized expression values, studies that require re-normalization from raw CEL files or unmapped FASTQ reads require supplementary data. Use getGEOSuppFiles() to retrieve the complete archive of supplementary files:
# Download all supplementary files for the series
supp_files <- getGEOSuppFiles(accession_id, makeDirectory = TRUE, baseDir = dest_folder)
print(supp_files)
This command downloads the study’s tar archives into a subfolder named after the accession, making raw instrument data available for custom low-level normalization pipelines in DNA microarray analysis.
How to read the output
Interpreting the output generated by GEOquery requires understanding how Bioconductor’s S4 object architecture models biological assays. When loading a series matrix with getGEO(), the returned object encapsulates three interconnected components within a single coordinated structure:
1. Assay Data (Assay Values): The quantitative matrix accessible via exprs(eset) or assay(se) contains numeric measurements. Each column header corresponds to an NCBI Sample Accession (e.g., GSM1051515), while each row header represents an array probe identifier (e.g., 1007_s_at) or a transcript identifier. Before conducting statistical modeling, check whether the values represent raw counts, normalized fluorescent intensities, or log2-transformed expression values. Microarray intensity data in GEO typically ranges from 0 to 16 when log2-transformed; values exceeding 100 generally indicate raw, non-log-transformed data requiring transformation via log2(exprs(eset) + 1).
2. Phenotypic Metadata (PhenoData): The pData(eset) data frame contains one row per sample, indexed by the exact same GSM identifiers found in the column names of the expression matrix. NCBI GEO records include standardized fields such as geo_accession, status, submission_date, last_update_date, and contact_name, alongside experimenter-defined characteristics. Experimenter fields frequently appear as characteristics_ch1, characteristics_ch1.1, and characteristics_ch1.2. Analysts typically clean and reformat these text strings into explicit categorical factors (e.g., control versus treated, disease stage, or donor age) for inclusion in linear model design matrices.
3. Feature Data (FeatureData): The fData(eset) data frame contains one row per probe or gene, indexed by the row names of the expression matrix. When AnnotGPL = TRUE is used, GEOquery maps platform probes to NCBI-curated gene symbols, Entrez identifiers, and chromosomal coordinates. When AnnotGPL = FALSE, fData() reflects only the submitter’s original platform table, which may contain platform-specific probe sequences or manufacturer IDs rather than current HUGO Gene Nomenclature Committee (HGNC) gene symbols.
4. Supplementary File Trees: When utilizing getGEOSuppFiles(), GEOquery returns a data frame listing the file names, byte sizes, and local storage paths of the downloaded assets. For Affymetrix array studies, the supplementary archive typically contains a .tar file containing individual .CEL.gz files. For modern RNA sequencing submissions, supplementary archives often host raw read count matrices, gene-level feature counts, or bedGraph peak files generated during upstream quantification.
Troubleshooting GEOquery
Working with large, remote genomics archives frequently introduces network, memory, and format challenges. The following solutions address the most common issues encountered when running GEOquery in research workflows.
Network timeouts and download interruptions
Genomics series containing hundreds of samples or multi-gigabyte supplementary archives can trigger default R network timeouts. If downloads terminate prematurely with timeout errors, increase R’s global download timeout before calling getGEO():
# Extend default download timeout to 15 minutes (900 seconds)
options(timeout = 900)
# Configure modern download method
options(download.file.method = "libcurl")
Additionally, NCBI periodically updates server protocols and firewall rules, migrating public FTP endpoints to HTTPS endpoints. Ensuring that the curl and httr packages are updated to their latest CRAN releases resolves most connection dropouts and handshake failures.
Handling memory exhaustion on large studies
Attempting to download and parse immense series (such as large-scale cancer consortia with thousands of samples) directly into memory can trigger memory allocation errors. To minimize memory consumption:
- Always retain
GSEMatrix = TRUE. Loading full SOFT files usingGSEMatrix = FALSErequires GEOquery to parse the entire text tree into nested R lists, consuming tenfold more RAM than the compact matrix format. - If only sample annotations are needed to assess study suitability, use the lightweight companion package
GEOmetadbto query study metadata via an offline SQLite database before initiating large file downloads. - After extracting necessary expression and phenotype matrices, remove intermediate list objects and execute
gc()to release allocated heap memory back to the operating system.
Missing or obsolete gene annotations
Microarray platforms manufactured decades ago often lack current gene symbols in their base platform definitions. If fData(eset) yields empty gene symbol columns or archaic probe identifiers, set AnnotGPL = TRUE inside getGEO(). If NCBI has not generated an annotated GPL file for that specific platform, use Bioconductor’s organism-specific annotation databases (such as org.Hs.eg.db for human or org.Mm.eg.db for mouse) paired with AnnotationDbi::mapIds() to map manufacturer probe IDs directly to current Ensembl and Entrez gene identifiers.
Parsing corrupt or partial download files
If a network connection breaks mid-stream, GEOquery may cache a truncated .soft.gz or .matrix.gz file in your local destination directory. Subsequent calls to getGEO() will detect the existing file and attempt to parse the corrupted archive, triggering decompression errors. To resolve this, delete the corrupted file from the local cache folder or designate a clean destination directory via destdir = tempdir() before re-running the download command.
Free alternatives to GEOquery
While GEOquery is the standard tool for importing NCBI GEO records into R, researchers can employ complementary and alternative open-source software packages depending on their computational platform, analytical programming language, and data scope.
| Tool Name | Primary Language / Interface | Source Repository | Primary Use Case and Data Scope | Key Advantages |
|---|---|---|---|---|
| GEOquery | R / Bioconductor | NCBI GEO | Programmatic retrieval of GEO records into ExpressionSet and SummarizedExperiment containers. | Native integration with Bioconductor statistical packages (limma, DESeq2); automatic metadata parsing. |
| GEOmetadb | R / SQLite | NCBI GEO | Fast SQL querying of full GEO metadata indexed into a local SQLite database. | Instant metadata search across thousands of studies without making live web requests to NCBI. |
| ArrayExpress / BioStudies | R / Bioconductor & REST | EMBL-EBI | Accessing European functional genomics archives and MAGE-TAB structured datasets. | Standardized European compliance; direct access to curated functional genomics experiments archived at EBI. |
| GEOfetch | Python / CLI | NCBI GEO & SRA | Command-line retrieval of GEO/SRA metadata formatted for Portable Encapsulated Projects (PEP). | Language-agnostic pipeline integration; automated sample table generation for Python and Snakemake pipelines. |
| ARCHS4 | Web / HDF5 / Python / R | NCBI GEO & SRA | Uniformly re-processed RNA-seq gene and transcript counts from human and mouse experiments. | Eliminates batch and pipeline discrepancies by reprocessing raw sequencing reads through a single Kallisto pipeline. |
Choosing among these alternatives depends on your analytical framework and research goals:
- Select GEOquery when conducting standard microarray re-analyses or working within the R Bioconductor ecosystem, where automated parsing into
ExpressionSetorSummarizedExperimentobjects accelerates downstream linear modeling. - Select GEOmetadb when designing high-throughput cohort screens across multiple GEO accessions to locate studies matching specific tissue, treatment, or disease criteria prior to downloading data files.
- Select GEOfetch when engineering automated Snakemake, Nextflow, or Python-based bioinformatics pipelines that require standardized sample metadata tables adhering to Portable Encapsulated Projects (PEP) standards.
- Select ARCHS4 when re-analyzing human or mouse RNA sequencing studies and seeking uniformly processed, gene-level raw count matrices to avoid batch biases introduced by varied upstream alignment algorithms.
The data table below compares the foundational architectural specifications, supported entity types, and extraction methods across NCBI GEO record classes and GEOquery parsing functions.
Frequently asked questions
What is GEOquery?
GEOquery is an open-source R package developed by Sean Davis and published through the Bioconductor project that acts as a bridge between the NCBI Gene Expression Omnibus (GEO) database and the R statistical computing environment. It automates the programmatic querying, downloading, and parsing of functional genomics experiments—including microarray and RNA sequencing studies—directly into standard R data containers such as ExpressionSet and SummarizedExperiment.
How do I install GEOquery?
Install GEOquery directly from Bioconductor using the BiocManager package in an active R session. Run if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") followed by BiocManager::install("GEOquery"). For development features, install the package source directly from GitHub using BiocManager::install("seandavi/GEOquery").
How do I download a dataset using GEOquery?
Use the primary workhorse function getGEO() by supplying a valid NCBI GEO accession identifier. For example, to download a complete series matrix, call gse <- getGEO("GSE42872", GSEMatrix = TRUE). This command retrieves the compressed Series Matrix file from NCBI, unpacks the archive, and returns a list containing one or more ExpressionSet objects populated with assay data and sample phenotypes.
What type of R object does getGEO() return?
The return type depends on the accession prefix queried. When retrieving a GEO Series (GSE) with GSEMatrix = TRUE, getGEO() returns a standard R list of Biobase::ExpressionSet (or SummarizedExperiment) objects. When retrieving a GEO Dataset (GDS), it returns a GEODataset object. When querying a single sample (GSM) or platform (GPL), it returns a specialized GEOSample or GEOPlatform S4 object containing header metadata lists and data tables.
Can GEOquery handle raw supplementary files?
Yes. GEOquery includes the dedicated function getGEOSuppFiles() to retrieve non-matrix supplementary files, including raw Affymetrix CEL files, Illumina raw scan data, processed peak files, and RNA-seq count tables. Calling getGEOSuppFiles("GSE42872") creates a local directory named after the accession, downloads all supplementary archives from NCBI, and returns a data frame detailing local file paths and sizes.
Sources
- Bioconductor: Bioconductor – GEOquery, checked 2026-11-16
- Bioconductor: Using the GEOquery Package, checked 2026-11-16
- Sean Davis: Get data from NCBI Gene Expression Omnibus (GEO) • GEOquery, checked 2026-11-16
- Sean Davis: Getting started with GEOquery • GEOquery, checked 2026-11-16
- GitHub: GitHub – seandavi/GEOquery: The bridge between the NCBI Gene Expression Omnibus and Bioconductor · GitHub, checked 2026-11-16
- Galaxy Tool Shed: Galaxy Tool Shed, checked 2026-11-16
Data: NCBI GEO Record Types and GEOquery R Object Mapping Specifications
Comparative specifications of NCBI Gene Expression Omnibus (GEO) record classes, accession prefixes, GEOquery retrieval functions, returned R object containers, and primary data accessors compiled from official Bioconductor documentation and package source manuals.
| Record Type | Biological Scope | Retrieval Function | Returned R Class | Primary Accessor Method | Core Data Payload |
|---|---|---|---|---|---|
| GEO Platform (GPL) | Array or sequencer instrument annotation and probe definitions | getGEO(GEO, AnnotGPL = TRUE) | GEOPlatform or data.frame | Table() or fData() | Probe identifiers, gene symbols, Entrez IDs, and genomic coordinates |
| GEO Sample (GSM) | Individual biological specimen, assay, or single hybridization | getGEO(GEO) | GEOSample | Table() and Meta() | Single-sample expression intensities, scan parameters, and clinical traits |
| GEO Series (GSE) | Complete multi-sample experimental study and experimental design | getGEO(GEO, GSEMatrix = TRUE) | list of ExpressionSet | exprs() and pData() | Coordinated assay expression matrix, sample phenotypes, and feature data |
| GEO Dataset (GDS) | Curated collection of biologically comparable samples assembled by NCBI | getGEO(GEO) | GEODataset | Table() or GDS2eSet() | Normalized expression matrix subset by curated biological variables |
| Supplementary Files (RAW) | Raw instrument outputs, unprocessed tarballs, and count tables | getGEOSuppFiles(GEO) | data.frame of file paths | untar() or read.table() | CEL files, fastq manifest tables, peak files, and raw count matrices |
Sources
- Bioconductor - GEOquery (accessed 2026-11-16)
- Using the GEOquery Package (accessed 2026-11-16)
- Getting started with GEOquery • GEOquery (accessed 2026-11-16)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







