scverse
diff --git a/‎.github/badges/tests.json‎
Lines changed: 1 addition & 1 deletion b/‎.github/badges/tests.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.mypy-baseline.txt‎
Lines changed: 725 additions & 0 deletions b/‎.mypy-baseline.txt‎
Lines changed: 725 additions & 0 deletions
diff --git a/‎.pre-commit-config.yaml‎
Lines changed: 26 additions & 8 deletions b/‎.pre-commit-config.yaml‎
Lines changed: 26 additions & 8 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 37 additions & 14 deletions b/‎CONTRIBUTING.md‎
Lines changed: 37 additions & 14 deletions
diff --git a/‎docs/src/SUMMARY.md‎
Lines changed: 2 additions & 2 deletions b/‎docs/src/SUMMARY.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎docs/src/en/alphafold.md‎
Lines changed: 3 additions & 0 deletions b/‎docs/src/en/alphafold.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎docs/src/en/archs4.md‎
Lines changed: 2 additions & 0 deletions b/‎docs/src/en/archs4.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎docs/src/en/g2p.md‎
Lines changed: 63 additions & 16 deletions b/‎docs/src/en/g2p.md‎
Lines changed: 63 additions & 16 deletions
@@ -1 +1 @@
-{"schemaVersion": 1, "label": "tests", "message": "386/400 passing", "color": "yellow"}
+{"schemaVersion": 1, "label": "tests", "message": "419/422 passing", "color": "brightgreen"}
@@ -26,6 +26,8 @@ exclude: |
     | gget/constants/
     | tests/fixtures/
     | tests/pytest_results.*\.txt
+    | \.github/badges/.*\.json
+    | \.mypy-baseline\.txt
   )
 repos:
   - repo: https://github.com/biomejs/pre-commit
@@ -44,16 +46,32 @@ repos:
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
         types_or: [python, pyi, jupyter]
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.13.0
+  # mypy is run through mypy-baseline: the ~550 pre-existing type errors are
+  # grandfathered in .mypy-baseline.txt, so this hook only fails on NEW type
+  # errors introduced by a change. Works on pre-commit.ci (which runs
+  # --all-files) because the baseline filters by error identity, not by file.
+  # To refresh the baseline after fixing errors:
+  #   mypy gget | mypy-baseline sync
+  # See https://github.com/scverse/gget/issues/216
+  - repo: local
     hooks:
-      - id: mypy
-        files: ^gget/
+      - id: mypy-baseline
+        name: mypy (new errors only, baseline-filtered)
+        entry: bash -c 'mypy gget | mypy-baseline filter'
+        language: python
+        pass_filenames: false
+        always_run: true
+        # Pin everything that affects mypy's output so the baseline stays
+        # reproducible across machines and pre-commit.ci (unpinned stubs drift
+        # and surface "new" errors that aren't real). Bump deliberately and
+        # re-sync the baseline when you do.
         additional_dependencies:
-          - pandas-stubs
-          - types-requests
-          - types-tqdm
-          - types-beautifulsoup4
+          - mypy==1.13.0
+          - mypy-baseline==0.7.4
+          - pandas-stubs==3.0.3.260530
+          - types-requests==2.33.0.20260518
+          - types-tqdm==4.68.0.20260608
+          - types-beautifulsoup4==4.12.0.20250516
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
 
@@ -38,37 +38,60 @@ Commit the changes once you are happy with them.
 
 ### ‼️ Self-review the following before creating a Pull Request ‼️
 
-1. Review the content for technical accuracy.
+1. Review the content for technical accuracy and biological relevance (who are your target users and is this useful to them?).
 2. Copy-edit the changes/comments for grammar, spelling, and adherence to the general style of existing gget code.
-3. Format and lint your code with [pre-commit](https://pre-commit.com/) (powered by [ruff](https://docs.astral.sh/ruff/)). Install the hooks once with `prek install` (or `pre-commit install`) so they run automatically on every commit, or run them on demand with `prek run --all-files` (or `pre-commit run --all-files`).
-4. Make sure the unit tests pass:
-    - The tested environments are defined in `pyproject.toml` under `[tool.hatch.envs.hatch-test]` (the single source of truth used by CI). Run the full matrix with `uvx hatch test`.
-    - For a quick single-environment run, install the test dependencies with `uv sync --group test` and run `uv run pytest -ra -v --cov=gget --cov-report=term-missing tests`. To also exercise the `gget cellxgene` module, install its extra (`uv sync --group test --extra cellxgene`) on Python 3.12/3.13 — its dependency has no wheels for newer Python versions yet, and that test skips itself when the dependency is absent.
-5. Add new unit tests if applicable:
-    - Arguments and expected results are stored in json files in ./tests/fixtures/
-    - Unit tests can be added to ./tests/test_*.py and will be automatically detected
-6. Make sure the edits are compatible with both the Python and the command line interface
+3. **Command line interface:** Make sure edits keep the Python function and the command-line interface in sync. Any change to a function's arguments must be reflected in both the Python signature and the CLI argument parser.
     - The command line interface and arguments are defined in ./gget/main.py
-8. Add new modules/arguments to the documentation if applicable:
+4. **Documentation:** Add new modules/arguments to the documentation if applicable:
     - The manual for each module can be added/edited in `./docs/src/en/*.md` (the Spanish version of the docs in `./docs/src/es/*.md` is automatically generated/updated, and does not need to be edited manually)
-    - List all edits in `./docs/src/en/updates.md`
+    - **Document all edits in `./docs/src/en/updates.md`.** Keep this brief and succinct.
+5. **Add unit tests:** Add new unit tests if applicable:
+    - Arguments and expected results are stored in json files in ./tests/fixtures/
+    - Unit tests can be added to ./tests/test_*.py and will be automatically detected
+6. **Run unit tests:** Make sure the unit tests pass:
+    - The tested environments are defined in `pyproject.toml` under `[tool.hatch.envs.hatch-test]` (the single source of truth used by CI). Run the full matrix with `uvx hatch test`.
+    - For a quick single-environment run, install the test dependencies with `uv sync --group test` and run `uv run pytest -ra -v --cov=gget --cov-report=term-missing tests`. To also exercise the `gget cellxgene` module, install its extra (`uv sync --group test --extra cellxgene`) on Python 3.12/3.13 — its dependency has no wheels for newer Python versions yet, and that test skips itself when the dependency is absent.
 
 If you have any questions, feel free to start a [discussion](https://github.com/scverse/gget/discussions) or create an issue as described above.
 
+### Keep PRs small and focused
+
+Reviewers move faster on small, focused PRs. Whenever possible:
+
+- **Scope each PR to a single `gget` module or issue**. If you find yourself changing more than one module to address several distinct concerns, please open them as separate PRs — one per module. Bug fixes and small refactors inside one module can be combined; cross-module work should be split.
+- **Don't bundle unrelated changes** (e.g. a bug fix plus a new feature plus a refactor) in the same PR.
+
 ### Pull Request
 
 When you're finished with the changes, [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request), also known as a PR.
 
+‼️ Please DO NOT commit AI-generated code without careful review.
+
 ‼️ Please make all PRs against the `dev` branch of the gget repository.
 
 - Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
 - Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge.
 - If you run into any merge issues, checkout this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues.
 
-Once you submit your PR, a gget team member will review your proposal. We may ask questions or request additional information.
+Once you submit your PR, a `gget` team member will review your proposal. We may ask questions or request additional information.
+
+### What runs automatically on your PR
+
+When you open a PR, a few checks run automatically — you don't need to set anything up:
+
+- **Linting & formatting** ([pre-commit.ci](https://pre-commit.ci)): runs [ruff](https://docs.astral.sh/ruff/) (lint + format), [biome](https://biomejs.dev/), and basic hygiene hooks. It **auto-fixes** formatting issues by pushing a commit to your branch; it only fails the check for problems it can't fix automatically (e.g. lint errors).
+- **Type checking** (mypy, via pre-commit.ci): newly introduced type errors fail this check.
+- **Unit tests** (`CI - tests`): the complete test suite for all modules runs on Python 3.12, 3.13, and 3.14.
+- **Build check**: confirms the package still builds and is publishable.
+
+Optional: You can run these manually first (especially `uvx hatch test` and `prek run --all-files`) to catch most issues before creating the PR.
+
+### Failing tests for modules you didn't touch
+
+The `gget` test suite hits real upstream databases (Ensembl, UniProt, NCBI, ARCHS4, Open Targets, ELM, etc.). When those services change their data or schemas — which they do regularly — tests for the affected modules can start failing without anyone changing `gget` itself. **If automated CI tests fail in your PR for a module you did not touch, you can safely ignore those failures** when judging whether your PR is ready to merge. The maintainers track upstream-drift failures separately and do not expect contributors to fix unrelated breakages as a condition of merging.
 
-### Your PR is merged!
+### Your PR gets merged!
 
-Congratulations! 🎉	 The gget team thanks you. ✨
+Congratulations! 🎉	 The `gget` team thanks you. ✨
 
 Once your PR is merged, your contributions will be publicly visible on the [gget repo](https://github.com/scverse/gget).
@@ -21,7 +21,7 @@
 * [gget diamond](en/diamond.md)  
 * [gget elm](en/elm.md)  
 * [gget enrichr](en/enrichr.md)  
-* [gget g2p](en/g2p.md)  
+* [gget g2p](en/g2p.md)
 * [gget gpt](en/gpt.md)  
 * [gget info](en/info.md)  
 * [gget muscle](en/muscle.md)
@@ -64,7 +64,7 @@
 * [gget diamond](es/diamond.md)  
 * [gget elm](es/elm.md)  
 * [gget enrichr](es/enrichr.md)  
-* [gget g2p](es/g2p.md)  
+* [gget g2p](es/g2p.md)
 * [gget gpt](es/gpt.md)  
 * [gget info](es/info.md)  
 * [gget muscle](es/muscle.md)
 
@@ -33,6 +33,9 @@ For higher accuracy, at the potential cost of longer inference times, set this t
 `-o` `--out`  
 Path to folder to save prediction results in (str). Default: "./[date_time]_gget_alphafold_prediction".  
 
+`-jhd` `--jackhmmer_savedir`  
+Path to a parent directory in which to store the temporary jackhmmer files (str). By default, `gget alphafold` creates a "tmp" folder in your home directory (`~/tmp/jackhmmer/`), which can take up to ~2 GB of disk space. Use this argument to place these temporary files elsewhere, e.g. on a disk with more free space. Default: None.  
+
 **Flags**  
 `-mfm` `--multimer_for_monomer`  
 Use multimer model for a monomer.  
 
@@ -5,6 +5,8 @@
 Find the most correlated genes to a gene of interest or find the gene's tissue expression atlas using [ARCHS4](https://maayanlab.cloud/archs4/).  
 Return format: JSON (command-line) or data frame/CSV (Python).
 
+> **Note on the data source:** `gget archs4` queries the legacy ARCHS4 HTTP endpoints at `maayanlab.cloud`, which are lightweight and still maintained. ARCHS4 has since launched a new site ([archs4.org](https://archs4.org)) with a larger, more up-to-date dataset, but its programmatic access is provided only via the [`archs4py`](https://github.com/MaayanLab/archs4py) package and multi-GB HDF5 downloads (there is currently no equivalent lightweight HTTP API to query). `gget archs4` therefore continues to use the legacy endpoints. A possible future migration is tracked in [issue 254](https://github.com/scverse/gget/issues/254).
+
 **Positional argument**  
 `gene`  
 Short name (gene symbol) of gene of interest, e.g. STAT4.  
 
@@ -2,34 +2,43 @@
 
 > Python arguments are equivalent to long-option arguments (`--arg`), unless otherwise specified. Flags are True/False arguments in Python.  The manual for any gget tool can be called from the command-line using the `-h` `--help` flag.  
 # gget g2p 🧬➜🧪
-Query the [Genomics 2 Proteins (G2P) portal](https://g2p.broadinstitute.org/) to link genes/proteins to residue-level structural and functional annotations (e.g. AlphaFold pLDDT, UniProt sites, predicted pockets, PTMs), the gene–transcript–protein–isoform–structure map, and isoform alignments.  
+Query the [Genomics 2 Proteins (G2P) portal](https://g2p.broadinstitute.org/) to link genes/proteins to residue-level structural and functional annotations, the gene–transcript–protein–isoform–structure map, and isoform alignments.
 
-Returns: A data frame with the requested G2P information.  
+The per-residue feature table is rich (~140 columns), including AlphaFold pLDDT, DSSP secondary structure, accessible surface area, UniProt sites (active/binding/domain/...), PhosphoSitePlus PTMs, fpocket / af2bind / p2rank pocket predictions, intra- and inter-chain hydrogen bonds, non-bonded interactions, disulfide bonds and salt bridges (from PDB and AlphaFold), the PFES (Protein Feature Enrichment Score) sub-scores used by G2P for missense variant interpretation, and per-residue MaveDB experimental functional scores. See the [`g2p-bis` documentation](https://github.com/broadinstitute/g2p-bis) for column descriptions.
+
+> Note: this module wraps the *public* G2P REST API. The variant overlays shown in the portal's web UI (gnomAD, ClinVar, HGMD) are not exposed by the public API and are therefore not available via `gget g2p` — use the portal directly for those.
+
+Returns: A data frame with the requested G2P information, or `None` if the query failed (network error, invalid arguments, or unknown gene/UniProt pair).
 
 This module was written by [Elarwei](https://github.com/Elarwei001).
 
-**Positional argument**  
-`gene`  
+At least one of `gene` or `--uniprot_id` is required — the other is resolved automatically via the UniProt REST API and cached.
+
+**Arguments (at least one of `gene` / `--uniprot_id` required)**  
+`gene` (positional)  
 Gene symbol, e.g. BRCA1.  
+If omitted, resolved from `--uniprot_id`. In this case, note that gene → UniProt accession lookup is approximate (it picks the canonical reviewed human Swiss-Prot entry only); for non-human organisms, unreviewed entries, or a specific isoform, pass `--uniprot_id` explicitly.  
 
-**Other required arguments**  
 `-u` `--uniprot_id`  
-UniProt accession, e.g. P38398. For `--resource alignment` this is the canonical isoform (e.g. P01130-1).  
-Tip: find a gene's UniProt ID with [`gget info`](info.md).  
+UniProt accession, e.g. P38398. If omitted, resolved from `gene`. For `--resource alignment` this is the canonical isoform (e.g. P01130-1) and is **required** (gene→UniProt lookup returns the base accession and cannot disambiguate isoforms).  
+Tip: find a gene's UniProt ID with [`gget search`](search.md) (to get a gene's Ensembl ID) and [`gget info`](info.md).  
 
 **Optional arguments**  
 `-r` `--resource`  
 Defines the type of information to return (default: 'features'):  
-`features`: Per-residue protein feature table (AlphaFold pLDDT, UniProt sites, secondary structure, predicted pockets, PTMs, etc.).  
-`map`: Gene → transcript → protein isoform → structure map (UniProt/Ensembl/RefSeq/PDB identifiers).  
+`features`: Per-residue protein feature table (~140 columns: AlphaFold pLDDT, UniProt sites, secondary structure, predicted pockets, PTMs, PFES, MaveDB scores, ...).  
+`map`: Gene → transcript → protein isoform → structure map (UniProt/Ensembl/RefSeq/PDB identifiers). The comma-joined `PDB Ids` column is augmented with a parsed `PDB Ids List` column (`list[str]`) for direct consumption (e.g. with [`gget pdb`](pdb.md)).  
 `alignment`: Residue-level sequence alignment between two isoforms (requires `--isoform`; `--uniprot_id` is the canonical isoform).  
 
 `-i` `--isoform`  
 Alternative isoform UniProt accession (e.g. P01130-2). Required when `--resource alignment`. Default: None.  
 
+`--residues`  
+Restrict the result to specific residue positions (applies to `--resource features` / `alignment` only). Command line: comma-separated list and/or inclusive ranges, e.g. `185,1775,1812` or `100-200` or `1-50,185`. Python: `int`, `list[int]`, `range`, or `set[int]`. Default: None (return all residues).
+
 `-o` `--out`  
 Path to the file the results will be saved in, e.g. path/to/directory/results.json. Default: Standard out.  
-Python: `save=True` will save the output in the current working directory.  
+Python: `save=True` will save the output as a CSV in the current working directory; `out="path/to/file.csv"` writes to an explicit path and takes precedence over `save`.
 
 **Flags**  
 `-csv` `--csv`  
@@ -42,36 +51,74 @@ Python: Use `verbose=False` to prevent progress information from being displayed
 
 ### Examples
 ```bash
-# Per-residue protein features for BRCA1 (AlphaFold pLDDT, UniProt sites, ...)
+# Per-residue protein features for BRCA1 (AlphaFold pLDDT, UniProt sites, ...).
+# The gene symbol is optional — it can be resolved from the UniProt accession.
+gget g2p -u P38398
+```
+```python
+# Python
+gget.g2p(uniprot_id="P38398", resource="features")
+```
+&rarr; Returns a data frame with one row per residue of the BRCA1 protein (UniProt P38398) and its structural/functional annotations.  
+
+<br/><br/>
+
+```bash
+# Same query, with the gene symbol passed explicitly
 gget g2p BRCA1 -u P38398
 ```
 ```python
 # Python
 gget.g2p("BRCA1", uniprot_id="P38398", resource="features")
 ```
-&rarr; Returns a data frame with one row per residue of the BRCA1 protein (UniProt P38398) and its structural/functional annotations.  
+
+<br/><br/>
+
+```bash
+# Symmetric: only the gene symbol — UniProt accession is resolved automatically
+# (canonical reviewed human Swiss-Prot entry).
+gget g2p BRCA1
+```
+```python
+# Python
+gget.g2p("BRCA1")
+```
+&rarr; Same as above. The resolved `P38398` is logged and is visible in the leading `uniprot_id` column.
+
+<br/><br/>
+
+```bash
+# Score only specific residue positions
+gget g2p BRCA1 -u P38398 --residues 185,1775,1812
+```
+```python
+# Python
+gget.g2p("BRCA1", uniprot_id="P38398", residues=[185, 1775, 1812])
+gget.g2p("BRCA1", uniprot_id="P38398", residues=range(100, 200))
+```
+&rarr; Returns only the requested residues from the per-residue feature table.
 
 <br/><br/>
 
 ```bash
 # Gene -> transcript -> isoform -> structure map (CSV)
-gget g2p BRCA1 -u P38398 -r map --csv
+gget g2p -u P38398 -r map --csv
 ```
 ```python
 # Python
-gget.g2p("BRCA1", uniprot_id="P38398", resource="map")
+gget.g2p(uniprot_id="P38398", resource="map")
 ```
 &rarr; Returns the mapping of BRCA1 to its UniProt isoforms, Ensembl/RefSeq identifiers, and PDB structures.  
 
 <br/><br/>
 
 ```bash
 # Residue-level alignment between two LDLR isoforms
-gget g2p LDLR -u P01130-1 -r alignment -i P01130-2
+gget g2p -u P01130-1 -r alignment -i P01130-2
 ```
 ```python
 # Python
-gget.g2p("LDLR", uniprot_id="P01130-1", resource="alignment", isoform="P01130-2")
+gget.g2p(uniprot_id="P01130-1", resource="alignment", isoform="P01130-2")
 ```
 &rarr; Returns the residue-level alignment between LDLR isoforms P01130-1 and P01130-2.
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-{"schemaVersion": 1, "label": "tests", "message": "386/400 passing", "color": "yellow"}`
	`1`	`+{"schemaVersion": 1, "label": "tests", "message": "419/422 passing", "color": "brightgreen"}`