GO (Gene Ontology) annotations are one of the main ways to label a gene's
function. QuickGO is a fast, web-based browser for the GO and Evidence &
Conclusion Ontology (ECO), maintained by the Gene Ontology Annotation (GOA)
group at EMBL-EBI.
It provides a centralised resource to explore the functional attributes of gene
products (proteins, RNA, and complexes). It is a primary tool for functional
annotation mapping since it allows you to link a gene (e.g., USH2A) to its
specific biological processes (e.g. sensory perception of light stimulus),
molecular functions, and cellular components.
Prerequisites
uv: Read the uv skill and follow its Setup instructions to ensure
uv is installed and on PATH.
User Notification: If .licenses/quickgo_database_LICENSE.txt does not
already exist in the workspace root directory then (1) prominently notify
the user to check the terms at https://www.ebi.ac.uk/QuickGO/ and
https://www.ebi.ac.uk/QuickGO/api/index.html, then (2) create the file
recording the notification text and timestamp.
Usage
This skill provides a Python CLI wrapper scripts/quickgo_tool.py that queries
the QuickGO REST API. It handles formatting the requests, respecting rate
limits, and safely storing the potentially large JSON responses.
Core Rules
Use the Wrapper: ALWAYS execute the provided helper scripts to query the
database rather than accessing the database directly. The scripts
automatically enforce the required rate limit gracefully.
Pagination & Limits: Restrict endpoints to a maximum of 100 results per
page using --limit 100 and the --page parameter for larger datasets.
Output Files: Always use the --output flag to save responses to a file
incrementally or parse via jq.
Evidence Codes: Prioritize experimental evidence () over
electronic () to avoid noisy predictions.
ECO:0000269
ECO:0000501
Taxon Filtering: Use --taxonId 9606 to restrict results to Human when
analysing clinical or human genomic data.
Notification: If this skill is used, ensure this is mentioned in the
output.
The tool has four main subcommands:
go: For retrieving information about GO terms (e.g. definitions,
ancestors, descendants, and slims). See
references/go_terms.md.
annotation: For finding functional annotations linking gene products
to GO terms. This is your primary functional mapper. See
references/annotations.md.
geneproduct: For resolving gene symbols (like PROC) to their formal
database identifiers. See
references/gene_products.md.
eco: For Evidence & Conclusion Ontology terms (used in annotations to
indicate how an annotation was derived, e.g. experimental vs electronic).
See references/eco_terms.md.
Common Workflows
1. Map a gene to its functions (Annotations)
To find out what a gene does, you must first resolve its symbol to a UniProtKB
ID, and then query its annotations. Often it is best to filter for experimental
evidence (e.g. ECO:0000269 for EXP, or others like IDA, IMP) to avoid noisy
electronic predictions.
# Step 1: Find the UniProtKB ID for human (9606) gene PROC
uv run scripts/quickgo_tool.py geneproduct search --query "PROC" --taxonId 9606 --limit 5 --output proc_id.json
# (Look at proc_id.json, observe the ID is e.g., UniProtKB:P04070)
# Step 2: Find experimental GO annotations for that ID
uv run scripts/quickgo_tool.py annotation search --geneProductId "UniProtKB:P04070" --taxonId 9606 --evidenceCode "ECO:0000269" --limit 50 --output proc_annotations.json
2. Find all genes in a pathway
To find all genes annotated to a specific GO term (e.g., GO:0003700 for
"transcription factor activity"):
# Find human genes with this specific molecular function
uv run scripts/quickgo_tool.py annotation search --goId "GO:0003700" --taxonId 9606 --limit 50 --output tf_genes.json
3. Explore the GO Hierarchy
To check if a specific GO term is a descendant of a broader category, or to
fetch its definition:
# Fetch term details (definitions, synonyms)
uv run scripts/quickgo_tool.py go terms --ids "GO:0003150" --output term_details.json
# Check ancestry (e.g., is GO:0001917 a child of something?)
uv run scripts/quickgo_tool.py go terms --ids "GO:0001917" --relation ancestors --output term_ancestors.json
4. Create a GO Slim Summary
If you have a list of candidate genes and want a high-level functional summary,
you can map them up to a predefined GO Slim. First, fetch the annotations for
the genes to extract their GO IDs, then pass those IDs to the slim endpoint:
# Step 1: Find GO IDs for candidate genes (e.g., via their UniProt IDs, fetching their annotations)
# ... (output yields e.g., GO:0006915,GO:0008219)
# Step 2: Create a slim summary from those specific GO IDs
uv run scripts/quickgo_tool.py go slim --slimsToIds "GO:0005575,GO:0008150,GO:0003674" --slimsFromIds "GO:0006915,GO:0008219" --output my_slim.json
