Skip to main content
v2026.11,986 entries · CC-BY 4.0

GEOquery: The Bioconductor R Package for NCBI GEO Data

Guide to GEOquery in R: install via BiocManager, getGEO commands, ExpressionSet parsing, clinical metadata extraction, and common troubleshooting steps.

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 using GSEMatrix = FALSE requires 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 GEOmetadb to 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 ExpressionSet or SummarizedExperiment objects 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

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.

NCBI GEO Record Types and GEOquery R Object Mapping Specifications
Record TypeBiological ScopeRetrieval FunctionReturned R ClassPrimary Accessor MethodCore Data Payload
GEO Platform (GPL)Array or sequencer instrument annotation and probe definitionsgetGEO(GEO, AnnotGPL = TRUE)GEOPlatform or data.frameTable() or fData()Probe identifiers, gene symbols, Entrez IDs, and genomic coordinates
GEO Sample (GSM)Individual biological specimen, assay, or single hybridizationgetGEO(GEO)GEOSampleTable() and Meta()Single-sample expression intensities, scan parameters, and clinical traits
GEO Series (GSE)Complete multi-sample experimental study and experimental designgetGEO(GEO, GSEMatrix = TRUE)list of ExpressionSetexprs() and pData()Coordinated assay expression matrix, sample phenotypes, and feature data
GEO Dataset (GDS)Curated collection of biologically comparable samples assembled by NCBIgetGEO(GEO)GEODatasetTable() or GDS2eSet()Normalized expression matrix subset by curated biological variables
Supplementary Files (RAW)Raw instrument outputs, unprocessed tarballs, and count tablesgetGEOSuppFiles(GEO)data.frame of file pathsuntar() or read.table()CEL files, fastq manifest tables, peak files, and raw count matrices

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about GEOquery: The Bioconductor R Package for NCBI GEO Data

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →