Contents

• Links

• Installation

• The three-layer API

• Quickstart

  • Python API

  • Command-line tool

• Data mirrors

• Dependencies

• Questions, Feature Requests, and Bug Reports

• License

• Citation

Links

• recount3 @ GitHub

• recount3 @ PyPI

• Documentation @ Pages

• Questions & bug reports @ Issues

Installation

The core package supports Python 3.10 through 3.15 and depends on NumPy, pandas, and SciPy. Five optional extras enable additional features:

python3 -m pip install recount3                # core
python3 -m pip install "recount3[biocpy]"      # + SummarizedExperiment builders
python3 -m pip install "recount3[bigwig]"      # + BigWig coverage access
python3 -m pip install "recount3[parquet]"     # + .parquet output
python3 -m pip install "recount3[anndata]"     # + .h5ad output
python3 -m pip install "recount3[pybiocfilecache]"  # shared R/Python cache
python3 -m pip install "recount3[all]"         # every optional feature

• biocpy (biocframe, genomicranges, summarizedexperiment) is required for create_rse and every helper that returns or operates on a BiocPy object.

• bigwig (pyBigWig) is required only for BigWig coverage access.

• parquet (pyarrow) is required only to write .parquet output. pandas accepts either pyarrow or fastparquet; an existing fastparquet installation is used as-is.

• anndata (anndata, delayedarray) is required only to write .h5ad output, and implies biocpy.

• pybiocfilecache enables opt-in R BiocFileCache interoperability. The default URL-hash cache is ~3x faster and needs no extra. Select sharing with RECOUNT3_CACHE_BACKEND=pybiocfilecache; it defaults to R’s recount3 cache directory (normally ~/.cache/R/recount3 on Linux/WSL). Explicit cache directories still take precedence. See “Cache and configuration” in the tutorial for concurrency, refresh semantics, maintenance, and measured overhead.

all installs every optional feature listed above. The dev and docs extras hold the test and documentation toolchains and are installed separately.

On Windows, substitute py -3 -m pip install .... Upgrade an existing installation with python3 -m pip install --upgrade recount3.

Note: The optional extras have platform constraints. The bigwig extra can be difficult or impossible to install on Windows and macOS. The biocpy extra can be difficult or impossible to install on Windows, and anndata inherits that constraint because it requires biocpy. On Python 3.15, anndata (and therefore all) cannot be installed yet: its h5py dependency publishes no Python 3.15 wheels, and building it from source requires the HDF5 C library. The parquet and pybiocfilecache extras install cleanly on every supported platform. The core package and the command-line workflow do not depend on any extra and work on all supported platforms.

The three-layer API

recount3 exposes the same workflow at three levels of abstraction, so a single project can be assembled in one call while multi-project or custom workflows retain full control:

• High level. create_rse() builds one project into a RangedSummarizedExperiment and performs discovery, downloading, metadata merging, and range assembly in a single call.

• Mid level. R3ResourceBundle is a filterable container of resources for combining multiple projects, selecting subsets, and stacking matrices.

• Low level. R3Resource represents a single file and manages its URL, cache entry, and parser.

See the Tutorial for a complete walkthrough.

Quickstart

>>> import recount3 as r3
>>>
>>> rse = r3.create_rse(
...     project="SRP009615",
...     organism="human",
...     annotation_label="gencode_v26",
... )
>>> rse.shape
(63856, 12)

>>> import recount3 as r3
>>>
>>> bundle = r3.R3ResourceBundle.discover(
...     organism="human",
...     data_source="sra",
...     project="SRP009615",
... )
>>> print(f"Found {len(bundle.resources)} resources.")
Found 10 resources.
>>>
>>> gene_counts = bundle.filter(
...     resource_type="count_files_gene_or_exon",
...     genomic_unit="gene",
...     annotation_extension="G026",
... ).stack_count_matrices(compat="feature")
>>> gene_counts.shape
(63856, 12)

# Search for gene-level count files and write a manifest.
recount3 search gene-exon \
    organism=human data_source=sra genomic_unit=gene project=SRP009615 \
    --format=jsonl > manifest.jsonl

# Materialize all resources from the manifest (8 parallel jobs).
recount3 download --from=manifest.jsonl --dest=./downloads --jobs=8

recount3 search annotations \
    organism=human genomic_unit=gene annotation_extension=G026 \
    --format=jsonl | \
recount3 download --from=- --dest=./annotations

recount3 bundle rse --from=manifest.jsonl --genomic-unit=gene --out=rse.pkl

Data mirrors

recount3 publishes the same relative file layout on several interchangeable public mirrors. recount3 targets this layout rather than any single host, so selecting a different mirror requires only a change to the base URL (the RECOUNT3_URL environment variable, the --base-url CLI flag, or the base_url field of recount3.config.Config):

Dependencies

Core (installed automatically):

numpy>=2.0
pandas>=2.2
scipy>=1.13

Optional: BiocPy integration (recount3[biocpy]):

biocframe>=0.7
genomicranges>=0.8
summarizedexperiment>=0.7.1

Optional: BigWig support (recount3[bigwig]):

pybigwig>=0.3.18

Optional: Parquet output (recount3[parquet]):

pyarrow>=23.0.1

Optional: AnnData output (recount3[anndata], implies biocpy):

anndata>=0.11
delayedarray>=0.5

Optional: shared R/Python cache (recount3[pybiocfilecache]):

pybiocfilecache>=0.7.0,<0.8

Questions, Feature Requests, and Bug Reports

Please submit questions, feature requests, and bug reports on Issues.

License

This package is distributed under The Clear BSD License with Extra Clause.

Citation

When using the recount3 Python package in published work, please cite:

• Alexander Alsalihi, Robert M Flight, and Hunter N.B. Moseley. “The recount3 Python package for programmatic access to uniformly processed RNA-seq data.” bioRxiv (2026). doi: 10.64898/2026.06.17.732943

If your work uses the recount3 data resource, please also cite the original recount3 publication:

• Wilks, C., Zheng, S.C., Chen, F.Y. et al. “recount3: summaries and queries for large-scale RNA-seq expression and splicing.” Genome Biology 22, 323 (2021). doi: 10.1186/s13059-021-02533-6