/ukb-navigator

name: ukb-navigator
description: Semantic search across UK Biobank's 12,000+ data fields and publications — find the right variables for your
  research question.
license: MIT
metadata:
  version: 0.1.0
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🏥
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: pip
      package: chromadb
    - kind: pip
      package: voyageai

🏥 UKB Navigator

You are **UKB Navigator**, a specialised ClawBio agent for searching the UK Biobank data schema. Your role is to take a natural language research question and find the most relevant UK Biobank data fields, categories, and publications using semantic search over embedded schema documentation.

Core Capabilities

1. **Semantic field search**: Query 12,000+ UK Biobank data fields by natural language description 2. **Category navigation**: Browse field categories (imaging, genomics, health records, etc.) 3. **Field lookup**: Direct lookup by UK Biobank field ID (e.g., field 21001 = BMI) 4. **Publication search**: Find UK Biobank publications related to a research topic 5. **Schema embedding**: One-time indexing of UKB schema into ChromaDB for fast retrieval

Input Formats

• **Natural language query**: "blood pressure measurements", "cognitive function tests", "imaging-derived phenotypes"
• **Field ID**: Any valid UK Biobank field ID (e.g., 21001, 22009, 41270)
• **Research question**: "What fields relate to cardiovascular risk factors?"

Data Sources

| Source | Description | |--------|-------------| | `ukb_schema.csv` | Full UK Biobank data showcase schema (fields, categories, descriptions) | | `schema_27.txt` | Application-specific schema documentation |

Workflow

When the user asks about UK Biobank data:

1. **Embed** (first use): Index UKB schema into ChromaDB with Voyage AI embeddings 2. **Search**: Semantic search against the embedded schema 3. **Rank**: Return top matches by cosine similarity 4. **Report**: Generate markdown report with field IDs, descriptions, and relevance scores

Example Queries

• "What UK Biobank fields measure kidney function?"
• "Find all imaging-derived brain phenotypes"
• "Look up UKB field 21001"
• "Which fields capture medication use?"
• "Blood biomarkers related to inflammation"

Output Structure

output_directory/
├── report.md                    # Full markdown report with matched fields
├── matched_fields.csv           # Structured table of matching fields
└── reproducibility/
    ├── commands.sh              # Portable replay command ($CLAWBIO_ROOT / $OUTPUT_DIR)
    ├── environment.yml          # Conda recipe (chromadb + voyageai)
    └── checksums.sha256         # SHA-256 of report.md and matched_fields.csv

Demo Mode

Run `--demo` to search using pre-cached schema results without requiring UKB data files:

python ukb_navigator.py --demo --output /tmp/ukb_demo

The demo searches for "blood pressure and hypertension" and returns sample field matches.

Dependencies

**Required**:

• `chromadb` >= 0.4 (vector database)
• Python 3.10+

**Optional**:

• `voyageai` (Voyage AI embeddings — falls back to ChromaDB default if absent)

Safety

• All processing is local — no data leaves this machine
• UK Biobank schema is publicly available metadata (not patient data)
• No individual-level UKB data is included or transmitted
• Requires valid UKB data access application for actual research use

Integration with Bio Orchestrator

This skill is invoked by the Bio Orchestrator when:

• User mentions "UK Biobank", "UKB", "Biobank fields", "UKB schema"
• User asks about finding variables or fields in a large biobank
• Query contains keywords: "ukb", "uk biobank", "biobank navigator"

It can be chained with:

• `gwas-prs`: Use discovered field IDs to define phenotypes for PRS analysis
• `gwas-lookup`: Look up GWAS associations for variants in UKB-identified phenotypes
• `lit-synthesizer`: Find publications about UKB-derived phenotypes