feat(alliance): add gget alliance module for Alliance of Genome Resources (#162)

[Elarwei001]

Resolves #162

Summary

gget alliance: new module to query the Alliance of Genome Resources — the consortium that integrates the major model-organism databases (human/HGNC, mouse/MGI, rat/RGD, zebrafish/ZFIN, fly/FlyBase, worm/WormBase, yeast/SGD, …). Two modes, chosen automatically from the input:

• Gene ID (e.g. HGNC:1101, MGI:109337, RGD:2219) → the gene's details.
• Free text → a search across genes / alleles / diseases / GO / variants / models, selectable with category.

Available in the Python API and on the command line.

Example return values

Mode A — fetch a gene by its Alliance ID — gget.alliance("HGNC:1101") (synonyms trimmed):

       id symbol                        name      species          taxon           gene_type              synonyms       data_provider
HGNC:1101  BRCA2 BRCA2 DNA repair associated Homo sapiens NCBITaxon:9606 protein_coding_gene  [FAD, FACD, FAD1, …]  RGD

Mode B — free-text search — gget.alliance("brca2", category="gene", limit=5). Note it spans organisms in one call:

                    id symbol                         name                 species           category         so_term_name
             HGNC:1101  BRCA2  BRCA2 DNA repair associated            Homo sapiens gene_search_result  protein_coding_gene
            MGI:109337  Brca2 breast cancer 2, early onset            Mus musculus gene_search_result  protein_coding_gene
              RGD:2219  Brca2 BRCA2, DNA repair associated       Rattus norvegicus gene_search_result  protein_coding_gene
        FB:FBgn0050169  Brca2 BRCA2, DNA repair associated Drosophila melanogaster gene_search_result  protein_coding_gene
ZFIN:ZDB-GENE-060510-3  brca2  BRCA2 DNA repair associated             Danio rerio gene_search_result  protein_coding_gene

Other categories work the same way — e.g. category="disease" returns disease objects (whose symbol / species / so_term_name are None, since the shared search schema is populated per object type). The counts differ by object type (for brca2: gene 40, disease 25, allele 107, variant 24307), so limit matters — a gene relates to a handful of diseases but tens of thousands of variants. First 2 of 25 disease hits:

          id                                    name              category
DOID:0111089 Fanconi anemia complementation group D1 disease_search_result
  DOID:11994                       atrophy of testis disease_search_result

With json=True (the command-line default) the same data comes back as a list of records — e.g. the gene fetch above (synonyms trimmed):

[
  {
    "id": "HGNC:1101",
    "symbol": "BRCA2",
    "name": "BRCA2 DNA repair associated",
    "species": "Homo sapiens",
    "taxon": "NCBITaxon:9606",
    "gene_type": "protein_coding_gene",
    "synonyms": ["FAD", "FACD", "FAD1", "BRCC2", "…"],
    "data_provider": "RGD"
  }
]

Options: category (gene / allele / disease / go / variant / model / all; default gene), limit (default 10), plus json / save.

Full example output — the gene detail (HGNC:1101), the full 40-row cross-organism gene search, and a disease search (CSV + JSON) are attached here: https://gist.github.com/Elarwei001/dde42935da5e9b09bf0ccb34e9176f4a

Testing

Unit tests in tests/test_alliance.py (fixture in tests/fixtures/) cover both modes, the friendly-category → API-value mapping, the {displayText/formatText} display objects, and the error paths (404 → gene not found, 5xx, request failure, empty term). Two live tests (skipped when offline, so CI stays green) hit the real Alliance API: a truth-anchored HGNC:1101 gene fetch and a brca2 gene search.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.80952% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 57.21%. Comparing base (e43a804) to head (7764c2c).
⚠️ Report is 2 commits behind head on dev.

Files with missing lines	Patch %	Lines
gget/gget_alliance.py	98.78%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #232      +/-   ##
==========================================
+ Coverage   56.70%   57.21%   +0.51%     
==========================================
  Files          29       30       +1     
  Lines        9392     9476      +84     
==========================================
+ Hits         5326     5422      +96     
+ Misses       4066     4054      -12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Elarwei001]

Hi @lauraluebbert — this PR is ready for review whenever you have time. Quick overview:

1. What it adds — gget alliance, a module to query the Alliance of Genome Resources (the consortium that integrates the major model-organism databases — HGNC, MGI, RGD, ZFIN, FlyBase, WormBase, SGD, …). Requested in Alliance Genome Resources #162.

2. How it works — two modes, chosen automatically from the input: an Alliance gene ID (e.g. HGNC:1101) fetches that gene's details via /gene, and free text queries /search (filter by category: gene / allele / disease / GO / variant / model). A search spans organisms in one call — e.g. brca2 returns the human, mouse, rat, fly, and zebrafish orthologs. Returns a DataFrame (or JSON), with category, limit, and json / save.
   Btw, the PR description has real return-value examples (table + JSON) and a full-output attachment as review reference.

3. Testing — unit tests cover both modes, the friendly-category to API-value mapping, the {displayText/formatText} display objects, and the error paths (404 to gene not found, 5xx, empty term). Two live tests (skipped when offline) hit the real Alliance API: a truth-anchored HGNC:1101 gene fetch and a brca2 gene search.

4. CI note — the only failing test is test_cellxgene_adata, which is unrelated to this PR (a cellxgene live-data drift, tracked in #265). It fails on py3.12/3.13 and is skipped on py3.14 (where cellxgene-census has no wheel). All gget alliance tests — including the two live API tests — pass on every version.

Happy to adjust anything — thanks!