seqout (Python Client & CLI)

A Python client library and command-line interface (CLI) for seqout.org. Use this package to search and retrieve genomics study metadata across GEO, SRA, ENA, DDBJ, ArrayExpress, GEA, and GSA, and download metadata, raw reads, and processed counts matrices.

Requires Python 3.13 or newer.

Installation

pip install seqout            # library + CLI
pip install "seqout[counts]"  # also read GEO supplementary files as counts matrices

As a standalone CLI, or as a project dependency, with uv:

uv tool install seqout
uvx seqout --help             # run once without installing
uv add "seqout[counts]"

The development version installs from GitHub:

pip install "seqout @ git+https://github.com/saketlab/seqout.git#subdirectory=python"

Quick start

Query from the command line

Run these commands to search for datasets, inspect study details, and download supplementary files:

# Search for GEO single-cell lung cancer studies, sorted by citations
seqout search "lung cancer single cell" --db geo --sort citations --max 5

# Show detailed metadata for a study
seqout show GSE149312

# Download processed supplementary files
seqout download GSE149312 --supplementary

Query in Python

Open a connection using connect() to search and query metadata programmatically:

from seqout import connect

with connect() as sq:
    dataset = sq.get("GSE149312")
    print(f"Title: {dataset.meta.title}")
    print(f"Samples: {len(dataset.samples)}")
    print(f"Runs: {len(dataset.runs)}")

The Dataset object evaluates fields lazily. It fetches data from the API only when you access a field for the first time, and caches it for future reads. It automatically resolves cross-archive links (for example, mapping a GEO series to its corresponding SRA study runs).

Parse processed single-cell matrices

To parse supplementary files into cell-by-gene expression matrices along with harmonized donor covariates, use SeqoutListCounts. This feature requires the counts installation extra:

from seqout import SeqoutListCounts

# Query the file manifest without downloading the files
counts = SeqoutListCounts(gse="GSE297547")
print(counts.manifest())

# Download and parse a specific sample unit into an AnnData object
matrix = counts.matrix(sample="GSM8994520")

# Access the harmonized experimental design table
print(counts.design)

Command reference summary

For the complete options list, run seqout --help or seqout <command> --help.

Explore metadata

Download files

Map accessions

Offline SQL queries (Parquet backend)

To run standard CLI commands offline, append the --parquet flag (e.g., seqout show GSE12345 --parquet).