quickgo-database

QuickGO Database Skill

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

1. uv: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.
2. 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 (ECO:0000269) over electronic (ECO:0000501) to avoid noisy predictions.
• 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:

1. go: For retrieving information about GO terms (e.g. definitions, ancestors, descendants, and slims). See references/go_terms.md.
2. annotation: For finding functional annotations linking gene products to GO terms. This is your primary functional mapper. See references/annotations.md.
3. geneproduct: For resolving gene symbols (like PROC) to their formal database identifiers. See references/gene_products.md.
4. 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