# Bioconductor Geoquery

> 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

- Skill: `biomate-ai/bioconductor-geoquery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/bioconductor-geoquery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/bioconductor-geoquery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/bioconductor-geoquery

---


# 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](https://www.biomate.ai?ref=kb&pkg=geoquery)** — free to start.

▶ **[Open `geoquery` on BioMate →](https://www.biomate.ai?ref=kb&pkg=geoquery)**