quickgo-database

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: quickgo-database
description: >
  Query the QuickGO and Evidence & Conclusion Ontology (ECO) REST API. Use this
  when you need to map genes to biological processes, molecular functions, or
  cellular components, find genes associated with a specific pathway/GO term, or
  explore the Gene Ontology hierarchy. Do not use for querying drug targets (use
  OpenTargets) or mechanistic signaling pathway diagrams (use KEGG).
---

# 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](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](references/annotations.md).
3.  **`geneproduct`**: For resolving gene symbols (like `PROC`) to their formal
    database identifiers. See
    [references/gene_products.md](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](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.

```bash
# 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., UniProt