feat(rummage): add gget rummagene and rummageo modules (#164)

docs/src/SUMMARY.md

@@ -29,6 +29,8 @@
 * [gget opentargets](en/opentargets.md)
 * [gget pdb](en/pdb.md)  
 * [gget ref](en/ref.md)  
+* [gget rummagene](en/rummagene.md)  
+* [gget rummageo](en/rummageo.md)  
 * [gget search](en/search.md)  
 * [gget setup](en/setup.md)  
 * [gget seq](en/seq.md)  

docs/src/en/rummagene.md

@@ -0,0 +1,53 @@
+[<kbd> View page source on GitHub </kbd>](https://github.com/scverse/gget/blob/main/docs/src/en/rummagene.md)
+
+> 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 rummagene 📚
+Find gene sets from PubMed Central (PMC) supplementary tables that overlap a query gene set using [Rummagene](https://rummagene.com/).  
+Rummagene automatically extracted ~1 million gene sets from the supplementary tables of open-access PMC articles. `gget rummagene` submits your gene list and returns the gene sets with the most significant overlap (Fisher's exact test).  
+Return format: JSON (command-line) or data frame/CSV (Python).
+
+**Positional argument**  
+`genes`  
+One or more gene symbols (HGNC), e.g. `STAT1 IRF1 OAS1`.
+
+**Optional arguments**  
+`-l` `--limit`  
+Maximum number of enriched gene sets to return. Default: 50.  
+
+`-ft` `--filter_term`  
+Only return gene sets whose term contains this (case-insensitive) substring. Default: None.  
+
+`-o` `--out`  
+Path to the file the results will be saved in, e.g. path/to/directory/results.csv (or .json). Default: Standard out.  
+Python: `save=True` will save the output in the current working directory.
+
+**Flags**  
+`-csv` `--csv`  
+Command-line only. Returns results in CSV format.  
+Python: Use `json=True` to return output in JSON format.
+
+`-q` `--quiet`  
+Command-line only. Prevents progress information from being displayed.  
+Python: Use `verbose=False` to prevent progress information from being displayed.  
+
+### Example
+```bash
+gget rummagene STAT1 STAT2 IRF1 IRF9 OAS1 MX1 ISG15 IFIT1 IFIT3 GBP1
+```
+```python
+# Python
+gget.rummagene(["STAT1", "STAT2", "IRF1", "IRF9", "OAS1", "MX1", "ISG15", "IFIT1", "IFIT3", "GBP1"])
+```
+&rarr; Returns the PMC-derived gene sets with the most significant overlap with the query genes, ranked by p-value.
+
+| rank | term | n_overlap | n_genes_in_set | odds_ratio | pval | adj_pval |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | PMC7617869-...-Type_I_IFN_signalling... | 10 | 34 | 602.6 | 3.7e-29 | 3.1e-23 |
+| . . . | . . . | . . . | . . . | . . . | . . . | . . . |
+
+# References
+If you use `gget rummagene` in a publication, please cite the following articles:  
+
+- Luebbert, L., & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. [https://doi.org/10.1093/bioinformatics/btac836](https://doi.org/10.1093/bioinformatics/btac836)
+
+- Clarke, D. J. B., et al. (2024). Rummagene: massive mining of gene sets from supporting materials of biomedical research publications. Communications Biology. [https://doi.org/10.1038/s42003-024-06177-7](https://doi.org/10.1038/s42003-024-06177-7)

docs/src/en/rummageo.md

@@ -0,0 +1,53 @@
+[<kbd> View page source on GitHub </kbd>](https://github.com/scverse/gget/blob/main/docs/src/en/rummageo.md)
+
+> 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 rummageo 🧬
+Find gene sets from Gene Expression Omnibus (GEO) studies that overlap a query gene set using [RummaGEO](https://rummageo.com/).  
+RummaGEO automatically computed differential-expression gene sets ("signatures") from hundreds of thousands of human and mouse GEO studies. `gget rummageo` submits your gene list and returns the gene sets with the most significant overlap (Fisher's exact test).  
+Return format: JSON (command-line) or data frame/CSV (Python).
+
+**Positional argument**  
+`genes`  
+One or more gene symbols, e.g. `STAT1 IRF1 OAS1`.
+
+**Optional arguments**  
+`-l` `--limit`  
+Maximum number of enriched gene sets to return. Default: 50.  
+
+`-ft` `--filter_term`  
+Only return gene sets whose term contains this (case-insensitive) substring. Default: None.  
+
+`-o` `--out`  
+Path to the file the results will be saved in, e.g. path/to/directory/results.csv (or .json). Default: Standard out.  
+Python: `save=True` will save the output in the current working directory.
+
+**Flags**  
+`-csv` `--csv`  
+Command-line only. Returns results in CSV format.  
+Python: Use `json=True` to return output in JSON format.
+
+`-q` `--quiet`  
+Command-line only. Prevents progress information from being displayed.  
+Python: Use `verbose=False` to prevent progress information from being displayed.  
+
+### Example
+```bash
+gget rummageo STAT1 STAT2 IRF1 IRF9 OAS1 MX1 ISG15 IFIT1 IFIT3 GBP1
+```
+```python
+# Python
+gget.rummageo(["STAT1", "STAT2", "IRF1", "IRF9", "OAS1", "MX1", "ISG15", "IFIT1", "IFIT3", "GBP1"])
+```
+&rarr; Returns the GEO-derived gene sets with the most significant overlap with the query genes, ranked by p-value.
+
+| rank | term | species | n_overlap | n_genes_in_set | odds_ratio | pval | adj_pval |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | GSE223635-8-vs-6-human up | human | 10 | 112 | 555.7 | 2.4e-28 | 4.1e-23 |
+| . . . | . . . | . . . | . . . | . . . | . . . | . . . | . . . |
+
+# References
+If you use `gget rummageo` in a publication, please cite the following articles:  
+
+- Luebbert, L., & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. [https://doi.org/10.1093/bioinformatics/btac836](https://doi.org/10.1093/bioinformatics/btac836)
+
+- Marino, G. B., et al. (2024). RummaGEO: Automatic Mining of Human and Mouse Gene Sets from GEO. Patterns. [https://doi.org/10.1016/j.patter.2024.101072](https://doi.org/10.1016/j.patter.2024.101072)

docs/src/en/updates.md

@@ -5,6 +5,7 @@
 #### *gget* officially became part of [*scverse*](https://scverse.org/) on June 9, 2026. 🥳🥳🥳
 
 **Version ≥ 0.30.9** (XXX XX, 2026):  
+- [`gget rummagene`](rummagene.md) and [`gget rummageo`](rummageo.md): **New modules** for gene set enrichment against gene sets automatically mined from PMC supplementary tables ([Rummagene](https://rummagene.com/)) and from GEO study signatures ([RummaGEO](https://rummageo.com/)). Submit a list of gene symbols to retrieve the most significantly overlapping literature/GEO gene sets (Fisher's exact test), ranked by p-value, via each service's public GraphQL API. Both share a single enrichment helper and support the `limit`, `filter_term`, `json`, and `save` options in the Python API and on the command line. Resolves [issue 164](https://github.com/scverse/gget/issues/164).
 
 **Version ≥ 0.30.8** (Jun 28, 2026):  
 - [`gget g2p`](g2p.md): Either `gene` or `--uniprot_id` is now sufficient — whichever is missing is resolved via UniProt and cached. Gene→UniProt picks the canonical reviewed human Swiss-Prot entry; the resolution and its limitations are logged. The canonical pair is **always** prepended to the result as `gene_name` / `uniprot_id` columns (and stored on `df.attrs`), so the output schema is invariant regardless of input mode. Existing call sites continue to work.

gget/__init__.py

@@ -23,6 +23,7 @@
 from .gget_opentargets import opentargets
 from .gget_pdb import pdb
 from .gget_ref import ref
+from .gget_rummage import rummagene, rummageo
 from .gget_search import search
 from .gget_seq import seq
 from .gget_setup import setup

gget/constants.py

@@ -7,6 +7,11 @@
 # strategy avoid hanging indefinitely on slow upstreams.
 DEFAULT_REQUESTS_TIMEOUT = (10, 60)
 
+# Rummagene & RummaGEO GraphQL API endpoints (gene set enrichment against gene
+# sets automatically extracted from PMC supplementary tables / GEO studies)
+RUMMAGENE_GRAPHQL_URL = "https://rummagene.com/graphql"
+RUMMAGEO_GRAPHQL_URL = "https://rummageo.com/graphql"
+
 # Ensembl REST API server for gget seq and info
 ENSEMBL_REST_API = "http://rest.ensembl.org/"
 ENSEMBL_FTP_URL = "http://ftp.ensembl.org/pub/"