| name | bioconductor-geoquery |
| description | This tool fetches microarray data directly from GEO database, based on the GEOQuery R package. Given a GSE accession ID, it returns an Rdata object containing the data and a text file (.cond file) summarizing the conditions of the experimen |
| when_to_use | Use when: 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 .. Not for: 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) d |
| user-invocable | false |
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
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 →
