Quickgo Database
- 1.3k installs
- 2.6k repo stars
- Updated July 7, 2026
- google-deepmind/science-skills
quickgo-database is a Google DeepMind science skill that queries Gene Ontology annotations and links genes to biological processes, molecular functions, and cellular components through the QuickGO API for developers buil
About
quickgo-database is a Gene Ontology annotations reference skill from google-deepmind/science-skills that drives the QuickGO annotation subcommand via quickgo_tool.py. Developers search GO annotations linking gene products to Biological Processes, Molecular Functions, and Cellular Components using filters like UniProtKB geneProductId, taxonId 9606, evidenceCode ECO:0000269, and GO term IDs. Example commands export JSON with --limit 50 through uv run scripts/quickgo_tool.py annotation search. The skill fits computational biology pipelines where functional enrichment, evidence filtering, and GO term lookup must be reproducible from the command line rather than manual web UI queries.
- Searches GO annotations for specific UniProtKB gene products
- Filters by GO ID, aspect (biological_process, molecular_function, cellular_component), taxon, and evidence code
- Supports experimental evidence (EXP=ECO:0000269) and descendant GO term usage
- Outputs structured results directly to JSON files for downstream agent workflows
- CLI-first integration with uv and Python for rapid biological data retrieval
Quickgo Database by the numbers
- 1,251 all-time installs (skills.sh)
- +166 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #267 of 2,064 Data Science & ML skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/google-deepmind/science-skills --skill quickgo-databaseAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1.3k |
|---|---|
| repo stars | ★ 2.6k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 7, 2026 |
| Repository | google-deepmind/science-skills ↗ |
How do you query Gene Ontology annotations from QuickGO?
Query Gene Ontology annotations and link genes to biological processes, molecular functions, and cellular components via the QuickGO API.
Who is it for?
Bioinformatics developers integrating QuickGO Gene Ontology annotation searches into Python or CLI pipelines with evidence-code and taxon filters.
Skip if: General web developers without genomics data needs should skip quickgo-database because it requires UniProtKB IDs and GO ontology context.
When should I use this skill?
A developer asks to query QuickGO, fetch GO annotations, or link genes to biological processes via the QuickGO API.
What you get
JSON annotation files linking gene products to GO biological process, function, and component terms.
- annotations.json export files
- GO term mapping results
- Filtered annotation search output
By the numbers
- Example annotation export uses --limit 50 on JSON output
- Documents taxonId 9606 and evidenceCode ECO:0000269 filter examples
Files
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 LICENSE_NOTIFICATION.txt does not already exist in this skill 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
--outputflag 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 9606to 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.json2. 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.json3. 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.json4. 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.jsonGene Ontology Annotations Reference
QuickGO annotation Subcommand
Use the annotation subcommand to search for GO annotations linked to gene products. This is the primary functional mapper linking a gene directly to Biological Processes, Molecular Functions, and Cellular Components.
Searching Annotations
# Find experimentally-validated (EXP=ECO:0000269) annotations for a specific UniProtKB ID
uv run scripts/quickgo_tool.py annotation search --geneProductId "UniProtKB:P04070" --taxonId 9606 --evidenceCode "ECO:0000269" --limit 50 --output annotations.json
# Find all annotations for a specific GO ID (e.g. apoptosis)
uv run scripts/quickgo_tool.py annotation search --goId "GO:0006915" --goUsage desc --taxonId 9606 --limit 50 --output apoptosis_annotations.json
# Find Biological Process annotations for a specific UniProtKB ID
uv run scripts/quickgo_tool.py annotation search --geneProductId "UniProtKB:P04637" --aspect "biological_process" --limit 50 --output p53_bp_annotations.jsonParameters:
-
--geneProductId: The database identifier for the gene product (e.g.,
UniProtKB:P04637).
-
--goId: The Gene Ontology ID (e.g.,GO:0006915). -
--aspect: Filter by GO aspect (biological_process,molecular_function,
cellular_component).
-
--taxonId: NCBI Taxonomy ID (e.g.,9606for Human). -
--evidenceCode: The ECO ID corresponding to the evidence type (e.g.,
ECO:0000269 for EXP, experimental evidence). Note that many electronic annotations are assigned ECO:0000501 (IEA).
-
--goUsage: How to use thegoIdparameter. Can beexact(only
annotations exactly matching the ID), desc (annotations matching the ID or any of its descendants), or slim (treat the IDs as a GO slim).
-
--qualifier: Qualifier such asenables,part_of,involved_in,
acts_upstream_of, etc.
-
--limit: Maximum number of results to return per page (max: 100, default:
25).
-
--page: Page number for pagination (default: 1). -
--output: The JSON file to save the results.
Evidence & Conclusion Ontology (ECO) Terms Reference
QuickGO eco Subcommand
Use the eco subcommand to search and retrieve details about Evidence & Conclusion Ontology terms. These terms are used as evidence codes in GO annotations (e.g. ECO:0000269 for "experimental evidence used in manual assertion").
1. Searching for ECO Terms
Search the Evidence & Conclusion Ontology for a specific query string.
uv run scripts/quickgo_tool.py eco search --query "experimental" --limit 5 --output eco_search_results.jsonParameters:
-
--query: The text you are looking for. -
--limit: Maximum number of results to return per page (max: 100, default:
25).
-
--page: Page number for pagination (default: 1). -
--output: The JSON file to save the results.
2. Getting ECO Term Details
Fetch detailed information about a specific ECO term or a set of ECO terms by their IDs.
# Get core attributes of an ECO term
uv run scripts/quickgo_tool.py eco terms --ids "ECO:0000269" --output eco_term_details.json
# Get ancestors of an ECO term
uv run scripts/quickgo_tool.py eco terms --ids "ECO:0000269" --relation ancestors --output eco_term_ancestors.jsonParameters:
-
--ids: Comma-separated list of ECO IDs (e.g., "ECO:0000269"). -
--relation: Optional. Can beancestors,descendants,children,
complete, or paths.
-
--output: The JSON file to save the results.
Gene Product Reference
QuickGO geneproduct Subcommand
Use the geneproduct subcommand to search for gene products across databases like UniProtKB, RNAcentral, and ComplexPortal. This is useful when you have a common gene symbol (e.g., "PROC") but you need its formal database identifier (e.g., "UniProtKB:P04070") to perform a strict annotation search.
Searching Gene Products
# Find gene product by symbol
uv run scripts/quickgo_tool.py geneproduct search --query "PROC" --limit 5 --output proc_gene_products.jsonParameters:
-
--query: The text you are looking for (e.g., a gene symbol like "PROC" or
"TP53").
-
--limit: Maximum number of results to return per page (max: 100, default:
25).
-
--page: Page number for pagination (default: 1). -
--output: The JSON file to save the results.
Gene Ontology (GO) Terms Reference
QuickGO go Subcommand
Use the go subcommand to search and retrieve details about Gene Ontology terms.
1. Searching for GO Terms
Search the Gene Ontology for a specific query string (e.g., biological processes, molecular functions, or cellular components).
uv run scripts/quickgo_tool.py go search --query "apoptosis" --limit 5 --output go_search_results.jsonParameters:
-
--query: The text you are looking for (e.g., "apoptosis", "transcription
factor").
-
--limit: Maximum number of results to return per page (max: 100, default:
25).
-
--page: Page number for pagination (default: 1). -
--output: The JSON file to save the results.
2. Getting GO Term Details
Fetch detailed information about a specific GO term or a set of GO terms by their IDs.
# Get core attributes of a GO term
uv run scripts/quickgo_tool.py go terms --ids "GO:0006915" --output term_details.json
# Get all children (direct descendants) of a GO term
uv run scripts/quickgo_tool.py go terms --ids "GO:0042995" --relation children --output term_children.json
# Get complete ancestry of a GO term
uv run scripts/quickgo_tool.py go terms --ids "GO:0001917" --relation ancestors --output term_ancestors.jsonParameters:
-
--ids: Comma-separated list of GO IDs (e.g., "GO:0006915"). -
--relation: Optional. Can beancestors,descendants,children,
complete, or paths.
-
--output: The JSON file to save the results.
3. GO Slims
GO Slims are a cut-down version of the Gene Ontology containing a subset of the terms. They give a broad overview of the ontology content without the detail of the specific fine-grained terms.
uv run scripts/quickgo_tool.py go slim --slimsToIds "GO:0005575,GO:0008150,GO:0003674" --output slim_results.jsonParameters:
-
--slimsToIds: Target GO IDs forming the slim set. -
--slimsFromIds: Optional source GO IDs from which slimming information is
applied.
-
--output: The JSON file to save the results.
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""A command-line tool for querying the QuickGO API.
This script provides subcommands to interact with various QuickGO API endpoints,
including searching for GO terms, ECO terms, annotations, and gene products.
Results are saved to a specified JSON file.
"""
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "scienceskillscommon",
# ]
# [tool.uv.sources]
# scienceskillscommon = { path = "../../scienceskillscommon" }
# ///
import argparse
import json
from typing import Any
import urllib.parse
from science_skills.skills.scienceskillscommon import http_client
BASE_URL = "https://www.ebi.ac.uk/QuickGO/services"
_CLIENT = http_client.HttpClient(BASE_URL, qps=10)
def make_request(path: str, params: dict[str, Any] | None = None) -> Any:
"""Makes a GET request to the QuickGO API.
Args:
path: The API endpoint path (e.g., "/ontology/go/search").
params: Optional dictionary of query parameters.
Returns:
The JSON response from the API.
"""
url = f"{BASE_URL}{path}"
if params:
url = f"{url}?{urllib.parse.urlencode(params, doseq=True)}"
return _CLIENT.fetch_json(url)
def save_output(data: Any, filename: str):
with open(filename, "w") as f:
json.dump(data, f, indent=2)
print(f"Successfully wrote results to {filename}")
def go_search(args: argparse.Namespace):
limit = min(args.limit, 100) if args.limit else 25
data = make_request(
"/ontology/go/search",
params={"query": args.query, "limit": limit, "page": args.page},
)
save_output(data, args.output)
def go_terms(args: argparse.Namespace):
path = f"/ontology/go/terms/{args.ids}"
if args.relation:
path += f"/{args.relation}"
if args.target_ids:
path += f"/{args.target_ids}"
data = make_request(path)
save_output(data, args.output)
def go_slim(args: argparse.Namespace):
params = {"slimsToIds": args.slimsToIds}
if args.slimsFromIds:
params["slimsFromIds"] = args.slimsFromIds
if args.relations:
params["relations"] = args.relations
data = make_request("/ontology/go/slim", params=params)
save_output(data, args.output)
def eco_search(args: argparse.Namespace):
limit = min(args.limit, 100) if args.limit else 25
data = make_request(
"/ontology/eco/search",
params={"query": args.query, "limit": limit, "page": args.page},
)
save_output(data, args.output)
def eco_terms(args: argparse.Namespace):
path = f"/ontology/eco/terms/{args.ids}"
if args.relation:
path += f"/{args.relation}"
data = make_request(path)
save_output(data, args.output)
def annotation_search(args: argparse.Namespace):
"""Searches for annotations using the QuickGO API.
Args:
args: An argparse namespace containing the command-line arguments.
Expected arguments include geneProductId, geneProductSubset,
geneProductType, goId, taxonId, evidenceCode, goUsage, qualifier, limit,
page, aspect, and output.
"""
params = {}
if args.geneProductId:
params["geneProductId"] = args.geneProductId
if args.geneProductSubset:
params["geneProductSubset"] = args.geneProductSubset
if args.geneProductType:
params["geneProductType"] = args.geneProductType
if args.goId:
params["goId"] = args.goId
if args.taxonId:
params["taxonId"] = args.taxonId
if args.evidenceCode:
params["evidenceCode"] = args.evidenceCode
if args.goUsage:
params["goUsage"] = args.goUsage
if args.qualifier:
params["qualifier"] = args.qualifier
if args.aspect:
params["aspect"] = args.aspect
if args.limit:
params["limit"] = min(args.limit, 100)
if args.page:
params["page"] = args.page
data = make_request("/annotation/search", params=params)
save_output(data, args.output)
def geneproduct_search(args: argparse.Namespace):
"""Searches for gene products using the QuickGO API.
Args:
args: An argparse namespace containing the command-line arguments.
Expected arguments include query, taxonId, limit, page, and output.
"""
params = {}
if args.query:
params["query"] = args.query
if args.taxonId:
params["taxonId"] = args.taxonId
if args.limit:
params["limit"] = min(args.limit, 100)
if args.page:
params["page"] = args.page
data = make_request("/geneproduct/search", params=params)
save_output(data, args.output)
def main():
parser = argparse.ArgumentParser(description="QuickGO API CLI Wrapper")
subparsers = parser.add_subparsers(dest="command", required=True)
# GO Subcommands
go_parser = subparsers.add_parser("go", help="Gene Ontology endpoints")
go_sub = go_parser.add_subparsers(dest="go_cmd", required=True)
go_search_p = go_sub.add_parser("search", help="Search GO terms by text")
go_search_p.add_argument(
"--query", required=True, help="Text query (e.g. 'apoptosis')"
)
go_search_p.add_argument(
"--limit", type=int, default=25, help="Max results per page (max 100)"
)
go_search_p.add_argument("--page", type=int, default=1, help="Page number")
go_search_p.add_argument("--output", required=True, help="Output JSON file")
go_search_p.set_defaults(func=go_search)
go_terms_p = go_sub.add_parser("terms", help="Get GO term details")
go_terms_p.add_argument("--ids", required=True, help="Comma-separated GO IDs")
go_terms_p.add_argument(
"--relation",
choices=["ancestors", "descendants", "children", "complete", "paths"],
help="Relationship type",
)
go_terms_p.add_argument(
"--target_ids", help="Target IDs (only used with 'paths' relation)"
)
go_terms_p.add_argument("--output", required=True, help="Output JSON file")
go_terms_p.set_defaults(func=go_terms)
go_slim_p = go_sub.add_parser("slim", help="Calculate GO Slims")
go_slim_p.add_argument("--slimsToIds", required=True, help="Target slim IDs")
go_slim_p.add_argument("--slimsFromIds", help="Source IDs")
go_slim_p.add_argument("--relations", help="Comma-separated relations")
go_slim_p.add_argument("--output", required=True, help="Output JSON file")
go_slim_p.set_defaults(func=go_slim)
# ECO Subcommands
eco_parser = subparsers.add_parser(
"eco", help="Evidence & Conclusion Ontology"
)
eco_sub = eco_parser.add_subparsers(dest="eco_cmd", required=True)
eco_search_p = eco_sub.add_parser("search", help="Search ECO terms by text")
eco_search_p.add_argument("--query", required=True)
eco_search_p.add_argument(
"--limit", type=int, default=25, help="Max results per page (max 100)"
)
eco_search_p.add_argument("--page", type=int, default=1, help="Page number")
eco_search_p.add_argument("--output", required=True)
eco_search_p.set_defaults(func=eco_search)
eco_terms_p = eco_sub.add_parser("terms", help="Get ECO term details")
eco_terms_p.add_argument("--ids", required=True)
eco_terms_p.add_argument(
"--relation",
choices=["ancestors", "descendants", "children", "complete", "paths"],
)
eco_terms_p.add_argument("--output", required=True)
eco_terms_p.set_defaults(func=eco_terms)
# Annotation Subcommands
ann_parser = subparsers.add_parser(
"annotation", help="Annotation search endpoints"
)
ann_sub = ann_parser.add_subparsers(dest="ann_cmd", required=True)
ann_search_p = ann_sub.add_parser("search", help="Search annotations")
ann_search_p.add_argument(
"--geneProductId", help="Gene product ID (e.g. UniProtKB:P04637)"
)
ann_search_p.add_argument(
"--geneProductSubset", help="Gene product subset (e.g. Swiss-Prot)"
)
ann_search_p.add_argument(
"--geneProductType", help="Gene product type (e.g. protein)"
)
ann_search_p.add_argument("--goId", help="GO ID (e.g. GO:0006915)")
ann_search_p.add_argument(
"--taxonId", type=int, help="NCBI Taxon ID (e.g. 9606 for human)"
)
ann_search_p.add_argument(
"--evidenceCode", help="Evidence code (e.g. ECO:0000269 for EXP)"
)
ann_search_p.add_argument(
"--goUsage", choices=["exact", "slim", "desc"], help="How to use goId"
)
ann_search_p.add_argument(
"--qualifier", help="Qualifier (e.g. enables, part_of, involved_in)"
)
ann_search_p.add_argument(
"--aspect",
choices=[
"biological_process",
"molecular_function",
"cellular_component",
],
help="GO aspect",
)
ann_search_p.add_argument(
"--limit", type=int, default=25, help="Max results per page (max 100)"
)
ann_search_p.add_argument("--page", type=int, default=1, help="Page number")
ann_search_p.add_argument("--output", required=True, help="Output JSON file")
ann_search_p.set_defaults(func=annotation_search)
# Gene Product Subcommands
gp_parser = subparsers.add_parser(
"geneproduct", help="Gene Product search endpoints"
)
gp_sub = gp_parser.add_subparsers(dest="gp_cmd", required=True)
gp_search_p = gp_sub.add_parser("search", help="Search gene products")
gp_search_p.add_argument(
"--query", required=True, help="Query string (e.g. PROC)"
)
gp_search_p.add_argument(
"--taxonId", type=int, help="NCBI Taxon ID (e.g. 9606 for human)"
)
gp_search_p.add_argument(
"--limit", type=int, default=25, help="Max results per page (max 100)"
)
gp_search_p.add_argument("--page", type=int, default=1, help="Page number")
gp_search_p.add_argument("--output", required=True, help="Output JSON file")
gp_search_p.set_defaults(func=geneproduct_search)
args = parser.parse_args()
args.func(args)
if __name__ == "__main__":
main()
Related skills
Microsoft FoundryDeploy, evaluate, and continuously improve Microsoft Foundry agents from a single agent interface.490k1.3k
Ai Research ReproductionOrchestrate trustworthy, auditable reproduction of deep learning repositories directly from their READMEs.176k511Run TrainSafely execute selected deep learning training commands with standardized evidence capture.176k511Explore RunSafely run isolated exploratory experiments with clear recording and conservative selection before committing changes.176k511Paper Context ResolverFetch precise reproduction-critical details like dataset splits, preprocessing steps, or evaluation protocols from the original academic paper when the repo README leav141k511Repo Intake And PlanScan unfamiliar AI research repositories and receive a minimal, trustworthy reproduction target before investing significant time.140k511How it compares
Choose quickgo-database over generic REST API skills when Gene Ontology evidence codes and UniProtKB gene product mapping are required.
FAQ
Which QuickGO subcommand does quickgo-database use?
quickgo-database centers on the QuickGO annotation subcommand accessed through scripts/quickgo_tool.py. That subcommand searches GO annotations linking gene products to Biological Processes, Molecular Functions, and Cellular Components.
What filters does quickgo-database support for annotation search?
quickgo-database supports filters including geneProductId for UniProtKB IDs, taxonId such as 9606 for human, evidenceCode like ECO:0000269 for experimental evidence, GO term IDs, and --limit 50 on JSON output.
Is Quickgo Database safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.