feat(encode): add gget encode module to query and download ENCODE data (#151)

docs/src/SUMMARY.md

@@ -20,6 +20,7 @@
 * [gget cosmic](en/cosmic.md)  
 * [gget diamond](en/diamond.md)  
 * [gget elm](en/elm.md)  
+* [gget encode](en/encode.md)  
 * [gget enrichr](en/enrichr.md)  
 * [gget g2p](en/g2p.md)
 * [gget gpt](en/gpt.md)  
@@ -63,6 +64,7 @@
 * [gget cosmic](es/cosmic.md)  
 * [gget diamond](es/diamond.md)  
 * [gget elm](es/elm.md)  
+* [gget encode](es/encode.md)  
 * [gget enrichr](es/enrichr.md)  
 * [gget g2p](es/g2p.md)
 * [gget gpt](es/gpt.md)  

docs/src/en/encode.md

@@ -0,0 +1,99 @@
+[<kbd> View page source on GitHub </kbd>](https://github.com/scverse/gget/blob/main/docs/src/en/encode.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 encode 🧫
+Query and download data from the [ENCODE project](https://www.encodeproject.org/).  
+`gget encode` has two modes, chosen automatically from the input:
+- If the input is an ENCODE **accession** (e.g. `ENCSR000AKS` for an experiment or `ENCFF000BXK` for a file), the matching object is fetched and its file(s) are returned (with download URLs). Use `--download` to fetch the files.
+- Otherwise, the input is used as a **free-text search** against the ENCODE search endpoint and the matching objects of the given `--type` are returned.
+
+Return format: JSON (command-line) or data frame/CSV (Python).
+
+**Positional argument**  
+`search_term`  
+ENCODE accession (e.g. `ENCSR000AKS` or `ENCFF000BXK`) or a free-text search term.
+
+**Optional arguments**  
+`-t` `--type`  
+ENCODE object type for free-text searches, e.g. `Experiment`, `File`, `Biosample`. Default: `Experiment`.  
+
+`-l` `--limit`  
+Maximum number of results for free-text searches. Default: 10.  
+
+`-a` `--assembly`  
+Only return files for this genome assembly, e.g. `GRCh38`. Default: None.  
+
+`-ff` `--file_format`  
+Only return files of this format, e.g. `bam`, `fastq`, `bigWig`. Default: None.  
+
+`-ot` `--output_type`  
+Only return files of this output type, e.g. `alignments`. Default: None.  
+
+`-od` `--out_dir`  
+Directory to download files into (used with `--download`). Default: current directory.  
+
+`-o` `--out`  
+Path to the file the results table 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**  
+`-d` `--download`  
+Download the returned files into the directory given by `--out_dir`. Only supported for ENCODE accessions (experiments/files).  
+
+`-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.  
+
+### Examples
+**Search for experiments:**
+```bash
+gget encode "CTCF K562"
+```
+```python
+# Python
+gget.encode("CTCF K562")
+```
+&rarr; Returns a table of ENCODE experiments matching the search term.
+
+| accession | assay_title | biosample_summary | target | description | status | lab |
+| --- | --- | --- | --- | --- | --- | --- |
+| ENCSR... | TF ChIP-seq | Homo sapiens K562 | CTCF | ... | released | ... |
+
+<br/><br/>
+**List the files of an experiment (filtered to GRCh38 BAMs):**
+```bash
+gget encode ENCSR000AKS --assembly GRCh38 --file_format bam
+```
+```python
+# Python
+gget.encode("ENCSR000AKS", assembly="GRCh38", file_format="bam")
+```
+&rarr; Returns a table of files (with download URLs) for the experiment.
+
+| file_accession | file_format | output_type | assembly | file_size | status | url |
+| --- | --- | --- | --- | --- | --- | --- |
+| ENCFF... | bam | alignments | GRCh38 | 123456 | released | https://www.encodeproject.org/files/ENCFF.../@@download/ENCFF....bam |
+
+<br/><br/>
+**Download the files into a directory:**
+```bash
+gget encode ENCSR000AKS --file_format bam --download --out_dir ./encode_data
+```
+```python
+# Python
+gget.encode("ENCSR000AKS", file_format="bam", download=True, out_dir="./encode_data")
+```
+&rarr; Downloads the matching files into `./encode_data`.
+
+> **Note:** `--download` fetches **every file left after filtering**. A single ENCODE experiment can contain dozens of files (tens of GB in total), and individual BAM/FASTQ files are often ~1 GB or larger. Always narrow the results with `--assembly`, `--file_format`, and/or `--output_type` before downloading.
+
+# References
+If you use `gget encode` in a publication, please cite the following articles:  
+
+- ENCODE Project Consortium. (2012). An integrated encyclopedia of DNA elements in the human genome. Nature. [https://doi.org/10.1038/nature11247](https://doi.org/10.1038/nature11247)
+
+- 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)

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 encode`](encode.md): **New module** to query and download data from the [ENCODE project](https://www.encodeproject.org/). Pass an ENCODE accession (e.g. `ENCSR000AKS` experiment or `ENCFF000BXK` file) to list its file(s) with download URLs — optionally filtered by `assembly`, `file_format`, and `output_type`, and downloaded with `download=True` — or pass a free-text term to search ENCODE objects of a given `type`. Available in the Python API and on the command line.
 
 **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

@@ -14,6 +14,7 @@
 from .gget_cosmic import cosmic
 from .gget_diamond import diamond
 from .gget_elm import elm
+from .gget_encode import encode
 from .gget_enrichr import enrichr
 from .gget_g2p import g2p
 from .gget_gpt import gpt

gget/constants.py

@@ -7,6 +7,9 @@
 # strategy avoid hanging indefinitely on slow upstreams.
 DEFAULT_REQUESTS_TIMEOUT = (10, 60)
 
+# ENCODE project REST API for gget encode
+ENCODE_URL = "https://www.encodeproject.org"
+
 # Ensembl REST API server for gget seq and info
 ENSEMBL_REST_API = "http://rest.ensembl.org/"
 ENSEMBL_FTP_URL = "http://ftp.ensembl.org/pub/"