feat(enrichr): retrieve gene sets incl. MSigDB collections (#139)

docs/src/en/enrichr.md

@@ -42,6 +42,21 @@ Short names (gene symbols) of background genes to perform enrichment analysis on
 Alternatively: use flag `--ensembl_background` to input a list of Ensembl gene IDs.  
 See [this Tweetorial](https://x.com/ChiHoangCaltech/status/1689679611335155712?s=20) to learn why you should use a background gene list when performing an enrichment analysis.  
 
+`-gl` `--get_library`  
+Instead of running an enrichment analysis, fetch the gene sets (members) of this Enrichr gene-set library, e.g. `MSigDB_Hallmark_2020`. This is the recommended way to retrieve [MSigDB](https://www.gsea-msigdb.org/gsea/msigdb/) gene sets (search for "MSigDB" in the [Enrichr library list](https://maayanlab.cloud/Enrichr/#libraries), e.g. `MSigDB_Hallmark_2020`, `MSigDB_Oncogenic_Signatures`, `MSigDB_Computational`). When set, the `genes` argument and `--database` are not required.  
+Python: `gget.enrichr_library("MSigDB_Hallmark_2020")`  
+
+`-gs` `--gene_set`  
+With `--get_library`: only return the genes of this single gene set (term) within the library, e.g. `Hypoxia`. (Default: None -> return all gene sets in the library.)  
+
+`-ll` `--list_libraries`  
+List the available Enrichr gene-set libraries (to discover library names), then exit. Optionally pass a substring to filter, e.g. `--list_libraries MSigDB`.  
+Python: `gget.enrichr_libraries(filter="MSigDB")`  
+
+`-desc` `--descriptions`  
+With `--get_library`: also include each gene set's description column.  
+Python: `descriptions=True`  
+
 `-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.  
@@ -222,6 +237,25 @@ df |>
 	xlab("-log10(adjusted P value)")
 ```
 
+<br/><br/>
+
+**Fetch the gene sets of an MSigDB collection (e.g. the Hallmark gene sets):**
+```bash
+gget enrichr --get_library MSigDB_Hallmark_2020 --csv
+```
+```python
+# Python
+import gget
+gget.enrichr_library("MSigDB_Hallmark_2020")
+```
+&rarr; Returns the 50 MSigDB Hallmark gene sets and their member genes as a long-format data frame (`gene_set`, `gene`). Add `--gene_set Hypoxia` (Python: `gene_set="Hypoxia"`) to return only one gene set. Use `--list_libraries MSigDB` (Python: `gget.enrichr_libraries(filter="MSigDB")`) to discover the available MSigDB collections.
+
+| gene_set                       | gene   |
+|--------------------------------|--------|
+| TNF-alpha&nbsp;Signaling&nbsp;via&nbsp;NF-kB | JUNB   |
+| TNF-alpha&nbsp;Signaling&nbsp;via&nbsp;NF-kB | CXCL2  |
+| ...                            | ...    |
+
 # Tutorials
 [Using `gget enrichr` with background genes](https://github.com/pachterlab/gget_examples/blob/main/gget_enrichr_with_background_genes.ipynb)
 
@@ -238,3 +272,11 @@ If you use `gget enrichr` in a publication, please cite the following articles:
 
 If working with non-human/mouse datasets, please also cite:
 - Kuleshov MV, Diaz JEL, Flamholz ZN, Keenan AB, Lachmann A, Wojciechowicz ML, Cagan RL, Ma'ayan A. modEnrichr: a suite of gene set enrichment analysis tools for model organisms. Nucleic Acids Res. 2019 Jul 2;47(W1):W183-W190. doi: [10.1093/nar/gkz347](https://doi.org/10.1093/nar/gkz347). PMID: 31069376; PMCID: PMC6602483.
+
+If retrieving MSigDB collections, please also cite:
+- Subramanian A, Tamayo P, Mootha VK, Mukherjee S, Ebert BL, Gillette MA, Paulovich A, Pomeroy SL, Golub TR, Lander ES, Mesirov JP. Gene set enrichment analysis: a knowledge-based approach for interpreting genome-wide expression profiles. Proc Natl Acad Sci USA. 2005;102(43):15545-15550. doi: [10.1073/pnas.0506580102](https://doi.org/10.1073/pnas.0506580102)
+- Liberzon A, Subramanian A, Pinchback R, Thorvaldsdóttir H, Tamayo P, Mesirov JP. Molecular signatures database (MSigDB) 3.0. Bioinformatics. 2011;27(12):1739-1740. doi: [10.1093/bioinformatics/btr260](https://doi.org/10.1093/bioinformatics/btr260)
+- Liberzon A, Birger C, Thorvaldsdóttir H, Ghandi M, Mesirov JP, Tamayo P. The Molecular Signatures Database (MSigDB) hallmark gene set collection. Cell Syst. 2015;1(6):417-425. doi: [10.1016/j.cels.2015.12.004](https://doi.org/10.1016/j.cels.2015.12.004)
+
+If using mouse MSigDB, please also cite:
+- Castanza AS, Recla JM, Eby D, Thorvaldsdóttir H, Bult CJ, Mesirov JP. Extending support for mouse data in the Molecular Signatures Database (MSigDB). Nat Methods. 2023;20:1619-1620. doi: [10.1038/s41592-023-02014-7](https://doi.org/10.1038/s41592-023-02014-7)

docs/src/en/updates.md

@@ -5,6 +5,9 @@
 #### *gget* officially became part of [*scverse*](https://scverse.org/) on June 9, 2026. 🥳🥳🥳
 
 **Version ≥ 0.30.9** (XXX XX, 2026):  
+- [`gget enrichr`](enrichr.md): Added support for retrieving gene sets, including [MSigDB](https://www.gsea-msigdb.org/gsea/msigdb/) collections (fixes [issue 139](https://github.com/scverse/gget/issues/139)).
+  - New `gget.enrichr_library()` function (command line: `gget enrichr --get_library`/`-gl`) fetches the gene sets (members) of any Enrichr gene-set library, e.g. `MSigDB_Hallmark_2020`, `MSigDB_Oncogenic_Signatures`, `MSigDB_Computational`.
+  - Returns a long-format DataFrame (`gene_set`, `gene`), or a `{gene_set: [genes]}` dictionary with `json=True`. Use `gene_set=` (command line: `--gene_set`/`-gs`) to return a single gene set, and the `species` argument for the non-human Enrichr variants.
 
 **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.

docs/src/es/enrichr.md

@@ -39,6 +39,21 @@ Opciones:
 Lista de nombres cortos (símbolos) de genes de 'background' (de fondo/control), p. NSUN3 POLRMT NLRX1.  
 Alternativamente: usa la bandera `--ensembl_background` para ingresar IDs tipo Ensembl.  
 
+`-gl` `--get_library`  
+En lugar de ejecutar el análisis de enriquecimiento, obtén los conjuntos de genes (miembros) de esta biblioteca de Enrichr, p. ej. `MSigDB_Hallmark_2020`. Es la forma recomendada de obtener conjuntos de genes de [MSigDB](https://www.gsea-msigdb.org/gsea/msigdb/) (busca "MSigDB" en la [lista de bibliotecas de Enrichr](https://maayanlab.cloud/Enrichr/#libraries)). Con esta opción, `genes` y `--database` no son necesarios.  
+Para Python: `gget.enrichr_library("MSigDB_Hallmark_2020")`  
+
+`-gs` `--gene_set`  
+Con `--get_library`: solo regresa los genes de este único conjunto de genes (término) dentro de la biblioteca, p. ej. `Hypoxia`. (Por defecto: None -> regresa todos los conjuntos de la biblioteca.)  
+
+`-ll` `--list_libraries`  
+Lista las bibliotecas de conjuntos de genes disponibles en Enrichr (para descubrir sus nombres) y termina. Opcionalmente pasa un texto para filtrar, p. ej. `--list_libraries MSigDB`.  
+Para Python: `gget.enrichr_libraries(filter="MSigDB")`  
+
+`-desc` `--descriptions`  
+Con `--get_library`: también incluye la columna de descripción de cada conjunto de genes.  
+Para Python: `descriptions=True`  
+
 `-o` `--out`  
 Ruta al archivo en el que se guardarán los resultados, p. ruta/al/directorio/resultados.csv (o .json). Por defecto: salida estándar (STDOUT).  
 Para Python, usa `save=True` para guardar los resultados en el directorio de trabajo actual.  
@@ -221,6 +236,19 @@ df |>
 
 #### [Más ejemplos](https://github.com/pachterlab/gget_examples)
 
+<br/><br/>
+
+**Obtén los conjuntos de genes de una colección de MSigDB (p. ej. los conjuntos Hallmark):**
+```bash
+gget enrichr --get_library MSigDB_Hallmark_2020 --csv
+```
+```python
+# Python
+import gget
+gget.enrichr_library("MSigDB_Hallmark_2020")
+```
+&rarr; Regresa los 50 conjuntos de genes Hallmark de MSigDB y sus genes miembros como un Dataframe en formato largo (`gene_set`, `gene`). Agrega `--gene_set Hypoxia` (Python: `gene_set="Hypoxia"`) para regresar un solo conjunto. Usa `--list_libraries MSigDB` (Python: `gget.enrichr_libraries(filter="MSigDB")`) para descubrir las bibliotecas MSigDB disponibles.
+
 # Citar  
 Si utiliza `gget enrichr` en una publicación, favor de citar los siguientes artículos:
 
@@ -234,3 +262,11 @@ Si utiliza `gget enrichr` en una publicación, favor de citar los siguientes art
 
 Si trabaja con conjuntos de datos no humanos/ratón, cite también:  
 - Kuleshov MV, Diaz JEL, Flamholz ZN, Keenan AB, Lachmann A, Wojciechowicz ML, Cagan RL, Ma'ayan A. modEnrichr: a suite of gene set enrichment analysis tools for model organisms. Nucleic Acids Res. 2019 Jul 2;47(W1):W183-W190. doi: [10.1093/nar/gkz347](https://doi.org/10.1093/nar/gkz347). PMID: 31069376; PMCID: PMC6602483.
+
+Si recupera colecciones de MSigDB, cite también:  
+- Subramanian A, Tamayo P, Mootha VK, Mukherjee S, Ebert BL, Gillette MA, Paulovich A, Pomeroy SL, Golub TR, Lander ES, Mesirov JP. Gene set enrichment analysis: a knowledge-based approach for interpreting genome-wide expression profiles. Proc Natl Acad Sci USA. 2005;102(43):15545-15550. doi: [10.1073/pnas.0506580102](https://doi.org/10.1073/pnas.0506580102)
+- Liberzon A, Subramanian A, Pinchback R, Thorvaldsdóttir H, Tamayo P, Mesirov JP. Molecular signatures database (MSigDB) 3.0. Bioinformatics. 2011;27(12):1739-1740. doi: [10.1093/bioinformatics/btr260](https://doi.org/10.1093/bioinformatics/btr260)
+- Liberzon A, Birger C, Thorvaldsdóttir H, Ghandi M, Mesirov JP, Tamayo P. The Molecular Signatures Database (MSigDB) hallmark gene set collection. Cell Syst. 2015;1(6):417-425. doi: [10.1016/j.cels.2015.12.004](https://doi.org/10.1016/j.cels.2015.12.004)
+
+Si utiliza MSigDB de ratón, cite también:  
+- Castanza AS, Recla JM, Eby D, Thorvaldsdóttir H, Bult CJ, Mesirov JP. Extending support for mouse data in the Molecular Signatures Database (MSigDB). Nat Methods. 2023;20:1619-1620. doi: [10.1038/s41592-023-02014-7](https://doi.org/10.1038/s41592-023-02014-7)

gget/__init__.py

@@ -14,7 +14,7 @@
 from .gget_cosmic import cosmic
 from .gget_diamond import diamond
 from .gget_elm import elm
-from .gget_enrichr import enrichr
+from .gget_enrichr import enrichr, enrichr_libraries, enrichr_library
 from .gget_g2p import g2p
 from .gget_gpt import gpt
 from .gget_info import info

gget/constants.py

@@ -60,6 +60,20 @@
 }
 GET_ENRICHR_URLS["human"] = GET_ENRICHR_URL
 
+# Enrichr endpoint to download the gene sets (membership) of a library, e.g. MSigDB collections
+GENESETLIBRARY_ENRICHR_URLS = {
+    f"{typ}": f"https://maayanlab.cloud/{typ.capitalize()}Enrichr/geneSetLibrary"
+    for typ in ["fly", "yeast", "worm", "fish"]
+}
+GENESETLIBRARY_ENRICHR_URLS["human"] = "https://maayanlab.cloud/Enrichr/geneSetLibrary"
+
+# Enrichr endpoint listing all available gene-set libraries (for library discovery)
+DATASETSTATISTICS_ENRICHR_URLS = {
+    f"{typ}": f"https://maayanlab.cloud/{typ.capitalize()}Enrichr/datasetStatistics"
+    for typ in ["fly", "yeast", "worm", "fish"]
+}
+DATASETSTATISTICS_ENRICHR_URLS["human"] = "https://maayanlab.cloud/Enrichr/datasetStatistics"
+
 # ARCHS4 API endpoints
 GENECORR_URL = "https://maayanlab.cloud/matrixapi/coltop"
 EXPRESSION_URL = "https://maayanlab.cloud/archs4/search/loadExpressionTissue.php?"