feat(mitocarta): new module to fetch the MitoCarta3.0 database (#118)

[Elarwei001]

Resolves #118

Summary

Adds a new gget mitocarta module that fetches the MitoCarta3.0 inventory of mammalian mitochondrial proteins and pathways (Broad Institute) and returns it as an analysis-ready ("tidy") pandas DataFrame or JSON — in both the Python API and on the command line.

MitoCarta3.0 is a manually curated inventory of ~1,100 human genes with strong evidence of mitochondrial localization, annotated with sub-mitochondrial localization, MitoPathways, and integrated (Maestro) localization scores. It is published only as static Excel files (no API), so this module downloads the .xls, selects the requested table, and normalizes it.

What it does

• species: human (default) or mouse (homo_sapiens / mus_musculus also accepted).
• which: which table to return —
  • mitocarta (default) — the curated inventory of mitochondrial genes;
  • all_genes — all ~19k genes with Maestro localization scores (same columns as mitocarta);
  • pathways — the MitoPathways hierarchy and the genes in each pathway.
• Returns a tidy DataFrame (or list[dict] with json=True); save=True writes a CSV/JSON to the working directory.

gget mitocarta --species human --which mitocarta
gget mitocarta --which pathways

import gget
gget.mitocarta("human", which="mitocarta")
gget.mitocarta("human", which="pathways")

Tidy normalization

The raw Excel is cleaned into an analysis-ready table rather than returned as-is:

• the pathways (C) sheet's stray unlabeled leading column (its header parses as an integer) is dropped, leaving MitoPathway / MitoPathways Hierarchy / Genes;
• delimited string columns are split into Python lists — Synonyms and MitoCarta3.0_MitoPathways (|-separated), and the pathways sheet's Genes (,-separated); missing values become [].

Column names and row counts are unchanged. (This changes the return shape of those columns from str to list — flagging for review.)

Download robustness

The download retries on transient network errors (3 attempts, linear backoff) — connection errors/timeouts and 5xx responses — and fails fast on 4xx (e.g. 404).

Testing

• Network-free unit tests: tidy cleaning (TestMitocartaClean) and retry (TestMitocartaRetry, mocked).
• Live tests hit the real Broad .xls (test_mitocarta_human, test_mitocarta_pathways). The len == 1136 assertion is intentional — the MitoCarta3.0 tables have not changed since 2023, so the count is stable.
• ruff clean.

Dependencies

Adds runtime dependency xlrd>=2 (to read the legacy .xls). Can be made an optional extra (gget[mitocarta]) if maintainers prefer.

Scope

Wraps only MitoCarta's .xls data tables (curated inventory + Maestro scores + pathways). It does not wrap the other MitoCarta3.0 distributions (.gmx, UCSC .bed, RefSeq .fasta, GFP images) — those serve narrower, tool-specific uses and could be added later on request.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 78.75000% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.13%. Comparing base (e43a804) to head (a1bd9da).
⚠️ Report is 2 commits behind head on dev.

Files with missing lines	Patch %	Lines
gget/gget_mitocarta.py	78.20%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #242      +/-   ##
==========================================
+ Coverage   56.70%   57.13%   +0.42%     
==========================================
  Files          29       30       +1     
  Lines        9392     9472      +80     
==========================================
+ Hits         5326     5412      +86     
+ Misses       4066     4060       -6     

☔ 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 adds a gget mitocarta module (resolves #118). Quick notes for review:

1. What it does — fetches the MitoCarta3.0 data from the Broad .xls and returns a tidy DataFrame or JSON (Python + CLI). Supported: human and mouse, across three tables — mitocarta (the curated inventory), all_genes (Maestro scores), and pathways (the MitoPathways hierarchy + member genes). Delimited fields (Synonyms, MitoCarta3.0_MitoPathways, pathway Genes) are split into lists, which become nested arrays in JSON.

2. Not (yet) covered — only MitoCarta's .xls tables are wrapped; the other distributions (.gmx, UCSC .bed, RefSeq .fasta, GFP images) are left out for now and can be added later on request. Tables are returned tidy, not reshaped into matrices (a one-line pivot for anyone who wants that).

3. How it's tested — network-free unit tests cover the table normalization and the download-retry logic (deterministic, no network); live tests download the real .xls and verify the expected tables and row counts. The download retries on transient network errors so the live tests stay stable.

Could you help review it when you are convenient? thanks

[Elarwei001]

The CI keep failed on "RuntimeError: http://rest.ensembl.org/ returned error status code 5xx", but locally run could pass.