bio-ortholog-inference

What this skill does

## Version Compatibility

Reference examples tested with: requests 2.31+, pandas 2.2+; OrthoDB v12 API, Ensembl REST (Ensembl release 112+), OMA REST API, eggNOG 6.0+, PANTHER v18+

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show requests pandas`
- API surface: confirm endpoint URLs and JSON schema match the current API docs

If endpoints return 404 or unexpected JSON, check release notes for the resource; schema migrations happen with each major version (Ensembl release is the biggest moving target).

# Ortholog Inference (Database Access)

**"What is the X ortholog of gene Y?"** -> Many ortholog resources have already done the inference at scale. Pulling their answers is faster and often more reliable than re-computing. This skill is the **database-access** view: how to query the major orthology resources programmatically, what their confidence semantics mean, and when their disagreements matter.

For **de novo orthology inference** (running OrthoFinder, SonicParanoid, OMA standalone on local proteomes), see `comparative-genomics/ortholog-inference` — that's a much deeper treatment of the computational side.

This skill is about pulling answers from:
- **OrthoDB v12** — broadest coverage (1700+ species), levels from species-specific to deep
- **Ensembl Compara** — vertebrate-focused, tree-reconciled, confidence scores
- **OMA browser** — high precision, HOG (Hierarchical Orthologous Group) framework
- **eggNOG 6.0** — pre-computed functional groups, deepest functional annotation
- **PANTHER** — protein family + ortholog calls with experimentally validated curation
- **KEGG Orthology (KO)** — pathway-centric orthologous functional units
- **HomoloGene** — deprecated since 2014, but data still queryable for legacy comparison

- Python: `requests.get()` against REST endpoints; `pandas` for parsing
- CLI: `curl` against the same endpoints; OrthoDB also has bulk downloads

## Required Setup

```python
import requests
import pandas as pd
import time
```

No API keys required for any of these resources (as of 2026), but rate limits apply — see per-resource notes below.

## Decision matrix: which resource for which question?

| Question | Resource | Why |
|---|---|---|
| Ortholog of human gene X in mouse | Ensembl Compara | Best-curated for vertebrates; confidence score per call |
| Ortholog of gene X across all 1700+ species | OrthoDB | Broadest taxonomic coverage |
| Single-copy orthologs for phylogenomics | OrthoDB at species-tree level | Pre-computed; large taxonomic groups |
| Functional annotation transfer | eggNOG-mapper or eggNOG API | OG-based functional categories |
| Pathway-centric orthology (KEGG pathways) | KEGG Orthology (KO) | KO IDs link directly to pathway maps |
| Curated function-aware orthologs | PANTHER | Smaller scope; manually curated; experiment-supported |
| Compare resource consensus | All of them + intersect | Disagreement is itself a signal |
| Plant orthology (Ensembl Plants) | Ensembl Compara (plant division) | Better than Ensembl vertebrate for plants |
| Bacterial orthology | OrthoDB or eggNOG bactNOG | Ensembl Bacteria has limited Compara coverage |
| Custom proteomes not in any database | **De novo computation** | See `comparative-genomics/ortholog-inference` |

## Per-resource API reference

### OrthoDB v12

Base URL: `https://data.orthodb.org/v12/`

Key endpoints (all GET, JSON returned):
- `/search?query=<symbol>&species=<NCBI_taxid>` — find ortholog groups by gene symbol
- `/orthologs?id=<og_id>&species=<taxid>` — get orthologs of a group at a specific level
- `/group?id=<og_id>` — full group info (sequences, evidence)
- `/tab?query=<og_id>` — tab-separated bulk dump

Levels are NCBI taxonomy IDs (e.g. 9606 = human, 40674 = Mammalia, 7742 = Vertebrata).

```python
def orthodb_search(symbol, species_taxid=9606):
    r = requests.get('https://data.orthodb.org/v12/search',
                     params={'query': symbol, 'species': species_taxid})
    r.raise_for_status()
    return r.json()['data']  # list of orthogroup IDs
```

### Ensembl Compara (via Ensembl REST)

Base URL: `https://rest.ensembl.org/`. JSON: `Accept: application/json`. Rate limit: 15 req/sec, 55,000 req/hour. Respect `Retry-After` on 429.

Key endpoints:
- `/homology/symbol/<species>/<symbol>` — orthologs of a gene by symbol
- `/homology/id/<ensembl_gene_id>` — orthologs of a gene by Ensembl ID
- `/lookup/symbol/<species>/<symbol>` — resolve symbol to Ensembl ID first
- Add `?type=orthologues` to filter to orthologs only (drop paralogs)
- Add `?target_species=<species>` to filter to one target species

```python
def ensembl_orthologs(symbol, species='human', target=None):
    url = f'https://rest.ensembl.org/homology/symbol/{species}/{symbol}'
    params = {'type': 'orthologues'}
    if target:
        params['target_species'] = target
    r = requests.get(url, params=params, headers={'Accept': 'application/json'})
    r.raise_for_status()
    homologies = r.json()['data'][0]['homologies']
    return [{
        'target_species': h['target']['species'],
        'target_id': h['target']['id'],
        'type': h['type'],  # ortholog_one2one / one2many / many2many / within_species_paralog
        'confidence': h.get('confidence'),  # 0/1; some calls lack this field
        'identity_target': h['target'].get('perc_id'),
        'identity_query': h['source'].get('perc_id'),
    } for h in homologies]
```

### OMA REST API

Base URL: `https://omabrowser.org/api/`. JSON returned. No rate-limit doc but be polite.

Key endpoints:
- `/protein/<id>/orthologs/` — orthologs of a protein (UniProt or OMA ID)
- `/hog/<hog_id>/` — Hierarchical Orthologous Group info
- `/genome/<species_code>/` — list all genomes; species codes are 5-letter (e.g. HUMAN, MOUSE)

```python
def oma_orthologs(uniprot_acc):
    r = requests.get(f'https://omabrowser.org/api/protein/{uniprot_acc}/orthologs/')
    r.raise_for_status()
    return r.json()  # list of ortholog dicts with omaid, canonicalid, taxonId
```

### eggNOG (5/6)

Base URL: `http://eggnog6.embl.de/api/` (web API; lighter than running eggNOG-mapper). Most heavy lifting still uses **eggNOG-mapper** locally (Cantalapiedra et al. 2021 *Mol Biol Evol* 38:5825) — for batch protein-set annotation, mapper > API.

For ad hoc lookup: search the eggNOG web interface for an orthogroup ID, then download the member set.

### KEGG Orthology (KO)

Base URL: `https://rest.kegg.jp/`. Returns plain text TSV by default (NOT JSON).

```python
def kegg_ko_for_gene(species_code, gene):
    '''KEGG species codes: hsa=human, mmu=mouse, dme=fly, etc.'''
    r = requests.get(f'https://rest.kegg.jp/link/ko/{species_code}:{gene}')
    r.raise_for_status()
    return [line.split('\t')[1].replace('ko:', '') for line in r.text.strip().split('\n') if line]


def kegg_orthologs(ko_id):
    r = requests.get(f'https://rest.kegg.jp/link/genes/{ko_id}')
    return [line.split('\t')[1] for line in r.text.strip().split('\n') if line]
```

KEGG license: commercial use requires a paid license; academic use is free for web/API.

### PANTHER

Base URL: `http://pantherdb.org/services/oai/pantherdb/` (note the unusual base). Has a curated, smaller scope than OrthoDB but with experimental evidence.

### HomoloGene (deprecated)

`https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=homologene&id=<id>&rettype=xml` — still works; data frozen since 2014. Useful only for backward-compatibility with old pipelines.

## Confidence-level semantics

Each resource defines "confidence" differently. They are NOT directly comparable.

| Resource | Confidence field | Semantics |
|---|---|---|
| Ensembl Compara | `confidence` 0/1 | Binary; 1 = high confidence based on gene-tree topology |
| OrthoDB | `evolutionary_rate` (not a confidence per se) | Inverse proxy; lower = more conserved |
| OMA | Internal QC; not exposed as a per-call score | All calls passed precision filter |
| eggNOG | Tax-level coverage | Member counts pe