GEOquery

Dependencies & Environment

Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.

• Version: 2.80.0 · Bioconductor: 3.23 · R: ≥ 4.6
• Depends: Biobase
• Imports: readr, xml2, dplyr, data.table, tidyr, magrittr, limma, curl, rentrez, R.utils, stringr, SummarizedExperiment, S4Vectors, rvest, httr2
• Install: BiocManager::install("GEOquery")

When to Use

• Downloading a complete GEO Series (GSE) matrix directly into a Bioconductor ExpressionSet using getGEO.
• Programmatically searching the GEO database for specific terms or metadata using searchGEO and searchFieldsGEO.
• Retrieving NCBI's standardized, precomputed RNA-seq gene expression counts for human and mouse datasets using getRNASeqData.
• Downloading supplementary files (e.g., raw single-cell .mtx or .h5 files, BED files) attached to GEO records using getGEOSuppFiles.

When NOT to Use

• For processing raw FASTQ files from SRA. Use standard alignment/quantification tools instead, as GEOquery is designed to retrieve precomputed counts or matrices.
• For analyzing local, non-GEO single-cell data. Use DropletUtils (e.g., read10xCounts) directly on your local files instead of routing through GEOquery.

Data Requirements

• A valid GEO accession identifier (e.g., GSE2553 for a Series, GSM15789 for a Sample, GPL96 for a Platform, or GDS507 for a Dataset).
• An active internet connection to access NCBI GEO FTP/HTTP servers.

Key Parameters

• GEO (e.g., "GSE2553"): The primary GEO accession string passed to getGEO or getGEOSuppFiles.
• GSEMatrix (default TRUE): Forces getGEO to use the faster, tab-delimited GSEMatrix files instead of the legacy SOFT format.
• AnnotGPL (default TRUE): Automatically includes GPL (Platform) annotation when retrieving GSE records.
• fetch_files (default TRUE): When set to FALSE in getGEOSuppFiles, it lists available supplementary files without downloading them.
• filter_regex: A regular expression string passed to getGEOSuppFiles to download only specific file types (e.g., 'txt').
• do.log2 (default TRUE): Applies a log2 transformation when converting a GDS object to an ExpressionSet using GDS2eSet.

Best Practices

• Use GSEMatrix = TRUE (the default) when downloading GSEs, as parsing is 10-100x faster and memory usage is more efficient than legacy SOFT files.
• Check if standardized RNA-seq quantifications are available using hasRNASeqQuantifications before attempting to download and process raw RNA-seq supplementary files.
• When dealing with older GDS datasets, convert them immediately to modern Bioconductor structures using GDS2eSet (for ExpressionSet) or GDS2MA (for limma's MAList).
• Use getGSEDataTables to extract additional metadata tables that might not be captured in the standard GSE structure.

Common Pitfalls

• Assuming a GSE returns a single object: getGEO returns a list of ExpressionSet objects because a single GSE can contain experiments from multiple platforms; fix this by indexing the list (e.g., gse[[1]]).
• Downloading massive supplementary files blindly: Running getGEOSuppFiles on a large GSE can download gigabytes of unwanted data; fix this by running with fetch_files = FALSE first to inspect the file list.
• Missing single-cell matrix components: Downloading just the .mtx file without barcodes and features; fix this by downloading the full tarball or all related supplementary files, then using DropletUtils::read10xCounts on the extracted prefix.

Alternatives

• DropletUtils: For reading the actual 10x single-cell files (read10xCounts) after GEOquery has downloaded them.
• limma: For downstream differential expression analysis of the ExpressionSet or MAList objects generated by GEOquery.

Citations

• Davis S, Meltzer P (2007). "GEOquery: a bridge between the Gene Expression Omnibus (GEO) and BioConductor." Bioinformatics, 14, 1846-1847. doi:10.1093/bioinformatics/btm254.

References

• Homepage: https://bioconductor.org/packages/GEOquery
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/GEOquery/inst/doc/GEOquery.html

<!-- biomate-cta -->

---

Run this on BioMate

This skill is the knowledge layer — when, why, and how to use geoquery. To run this analysis on your own data with managed compute, automated QC, and reproducible outputs, use BioMate — free to start.

▶ Open geoquery on BioMate →