gget

Overview

gget is a command-line bioinformatics tool and Python package providing unified access to 20+ genomic databases and analysis methods. Query gene information, sequence analysis, protein structures, viral sequences, expression data, disease associations, and mouse tissue/cell specificity metrics through a consistent interface. Most gget modules work both as command-line tools and as Python functions.

Important: The databases queried by gget are continuously updated, which sometimes changes their structure. Guidance here targets gget 0.30.8 (reviewed 2026-09-30). For reproducible work, pin gget==0.30.8; for broken upstream database adapters, update gget after checking release notes.

Installation

Install gget in a clean virtual environment to avoid conflicts:

# Reproducible install targeting this skill
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install "gget==0.30.8"

import gget

Quick Start

Inspect module-specific syntax before querying:

gget info --help
gget pdb --help

Most modules return:

• Command-line: JSON (default) or CSV with -csv flag
• Python: DataFrame or dictionary

Common flags across modules:

• -o/--out: Save results to file
• -q/--quiet: Suppress progress information
• -csv: Return CSV format (command-line only)

Python argument names generally match long CLI options without leading dashes. For example, --census_version becomes census_version=.... Use gget <module> --help for CLI syntax and inspect.signature(gget.<module>) for Python; CLI flags such as --download may have no Python equivalent.

Module Categories

gget exposes 24 modules in six categories. Parameters, CLI and Python examples, and return shapes for every one are in references/module_catalog.md; fuller per-parameter documentation is in references/module_reference.md.

Several modules need a one-time gget setup before first use (elm, cellxgene, cbio; legacy alphafold/gpt), and cosmic prompts for COSMIC credentials to download its database.

Common Workflows

Worked multi-module pipelines — gene characterization, structural comparison, expression and enrichment analysis, disease and drug association, orthology comparison, and reference-file preparation for kallisto or alignment — are in references/common_workflows.md, with longer versions in references/workflows.md.

Best Practices

Data Retrieval

• Use --limit where supported; it is often a local cap, not a complete pagination mechanism
• Save results with -o/--out for reproducibility
• Check database versions/releases for consistency across analyses
• Use --quiet in production scripts to reduce output

Sequence Analysis

• For BLAST/BLAT, start with default parameters, then adjust sensitivity
• Use gget diamond with --threads for faster local alignment
• Save DIAMOND databases with --diamond_db; gget still requires the reference input
• For multiple sequence alignment, use -s5/--super5 for large datasets

Expression and Disease Data

• Gene symbols are case-sensitive in cellxgene (e.g., 'PAX7' vs 'Pax7')
• Install optional dependencies for cellxgene, elm, and cbio with gget setup <module>
• For enrichment, record the full library name and release, not only a shortcut: the adapter maps shortcuts to specific dated libraries, and non-human/mouse species need full species-specific names. For human/mouse, supply the tested-gene universe through background_list when appropriate; custom backgrounds are not supported for the other species. Report mapped/unmapped query and background counts and adjusted p-values, so identifier loss and selection bias are visible.
• Cache cBioPortal data with -dd to avoid repeated downloads
• Open Targets filters are local and applied after limit; expression fetches only the first page (at most 3000 rows). Other paginated resources use the server default page. Do not treat results as exhaustive.
• gget.info returns IDs in its index; preserve that index when saving CSV. ARCHS4 tissue labels use id, correlations use pearson_correlation; Enrichr uses path_name and adj_p_val.
• gget.search matches descriptions and synonyms; select an exact gene_name and reject ambiguity instead of taking the first result.
• Census meta_only=True returns cells, not datasets, and ignores the gene filter. Scope by dataset/cell metadata and pin a dated Census release.

Structures and residue annotations

• Prefer gget.pdb(..., resource="mmcif") for explicit structure format; the PDB default can fall back to mmCIF.
• Use gget.g2p for existing residue annotations and isoform/structure maps; specify accessions for exact isoform identity.
• alphafold and gpt are deprecated and no longer maintained upstream. Existing examples are legacy/illustrative, not tested prediction or generation workflows.

Viral Data

• Use restrictive filters with gget virus before requesting broad viral datasets
• Keep command_summary.txt with downstream results for reproducibility and recovery after partial downloads
• Use --baseline and --merge-results to resume interrupted viral metadata/sequence downloads

Error Handling

• Database structures change; when an adapter breaks, check upstream release notes and pin the newer fixed version explicitly
• Pin the reviewed version for reproducible environments: uv pip install "gget==0.30.8"
• Process max ~1000 Ensembl IDs at once with gget info
• For large-scale analyses, implement rate limiting for API queries
• Use virtual environments to avoid dependency conflicts
• Keep COSMIC and OpenAI credentials in named environment variables or interactive prompts; do not write real credentials into examples, notebooks, or logs

Output Formats

Command-line

• Default: JSON
• CSV: Add -csv flag
• FASTA: gget seq, gget mutate
• PDB/mmCIF: gget pdb; legacy gget alphafold writes predicted structures
• PNG: gget cbio plot
• FASTA/CSV/JSONL folder: gget virus

Python

• Default: DataFrame or dictionary
• JSON: use json=True only on modules that support it (not g2p)
• Save to file: use only the module-specific save/out parameter; ref(download=True) and muscle(save=True) are invalid Python calls
• AnnData: gget cellxgene
• DataFrame/JSON: gget 8cube specificity, psi_block, expression

Bundled scripts and verification

• scripts/gene_analysis.py TP53: exact-symbol lookup, annotation/sequence export, optional human association queries; mouse tissue expression is routed correctly.
• scripts/enrichment_pipeline.py genes.txt --background tested_genes.txt: saves full dated library names and adjusted p-values. Use repeated --database for species-specific libraries. Failed queries are not negative evidence.
• scripts/batch_sequence_analysis.py proteins.fasta: small exploratory BLAST batches and local alignment; use local tools for large batches. The legacy --predict-structure flag only displays a placeholder.

The 0.30.8 adapters were source-checked, and tests use current response fields. Public reads verified ARCHS4, Open Targets, RCSB, Bgee, G2P, 8cube, Ensembl references/search. Ensembl info/seq failed on the released HTTP REST endpoint in this review; do not interpret that as a missing gene. Authenticated COSMIC, deprecated wrappers, and large downloads were not executed. Extended examples are explicitly illustrative. See database contracts for transport and completeness limitations.

Resources

This skill includes reference documentation for detailed module information:

references/

• module_reference.md - Selected parameters and Python/CLI differences
• database_info.md - Service contracts, pagination, and verification boundaries
• workflows.md - Extended workflow examples and use cases

For additional help:

• Official documentation: https://scverse.org/gget/
• GitHub issues: https://github.com/scverse/gget/issues
• Citation: Luebbert, L. & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. https://doi.org/10.1093/bioinformatics/btac836