Metadata-Version: 2.4
Name: recount3
Version: 1.0.0
Summary: CLI and API for searching, manifesting, and downloading recount3 resources.
Author: Alexander A. Alsalihi, Robert M. Flight, Hunter N.B. Moseley
Maintainer: Moseley Bioinformatics Lab
License-Expression: BSD-3-Clause-Clear
Project-URL: Homepage, https://github.com/MoseleyBioinformaticsLab/recount3
Project-URL: Repository, https://github.com/MoseleyBioinformaticsLab/recount3
Project-URL: Issues, https://github.com/MoseleyBioinformaticsLab/recount3/issues
Project-URL: Documentation, https://moseleybioinformaticslab.github.io/recount3/
Keywords: bioinformatics,genomics,recount3,RNA-seq,CLI,data-pipelines,manifests
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy<3.0,>=2.0
Requires-Dist: pandas<3.0,>=2.2
Requires-Dist: scipy<2.0,>=1.13
Provides-Extra: bigwig
Requires-Dist: pybigwig>=0.3.18; extra == "bigwig"
Provides-Extra: biocpy
Requires-Dist: biocframe>=0.7; extra == "biocpy"
Requires-Dist: genomicranges>=0.8; extra == "biocpy"
Requires-Dist: summarizedexperiment>=0.6; extra == "biocpy"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<6,>=5; extra == "dev"
Requires-Dist: pytest-mock<4,>=3.12; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3; extra == "dev"
Requires-Dist: pylint<4,>=3.2; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: commitizen>=3.29; extra == "dev"
Provides-Extra: all
Requires-Dist: recount3[bigwig,biocpy,dev,docs]; extra == "all"
Dynamic: license-file

recount3
========

.. image:: https://img.shields.io/pypi/l/recount3.svg
   :target: https://github.com/MoseleyBioinformaticsLab/recount3/blob/main/LICENSE
   :alt: Clear BSD License with extra clauses

.. image:: https://img.shields.io/pypi/v/recount3.svg
   :target: https://pypi.org/project/recount3
   :alt: Current library version

.. image:: https://img.shields.io/pypi/pyversions/recount3.svg
   :target: https://pypi.org/project/recount3
   :alt: Supported Python versions

.. image:: https://img.shields.io/github/stars/MoseleyBioinformaticsLab/recount3.svg?style=social&label=Star
   :target: https://github.com/MoseleyBioinformaticsLab/recount3
   :alt: GitHub project

|

The ``recount3`` package is a Python library and command-line tool for
interacting with the `recount3`_ data repository, a uniformly processed
collection of RNA-seq studies covering human and mouse samples from SRA,
GTEx, and TCGA.

The package provides a typed API for discovering, downloading, and assembling
recount3 resources into analysis-ready objects.  A companion CLI implements a
discover -> manifest -> materialize workflow suitable for use in scripts and
pipelines.

The ``recount3`` package can be used in two ways:

   * As a Python library for searching, downloading, and assembling
     recount3 gene/exon/junction count matrices, sample metadata, genome
     annotations, and BigWig coverage files into
     ``SummarizedExperiment`` / ``RangedSummarizedExperiment`` objects via
     the BiocPy stack.
   * As a command-line tool (``recount3``) to search the mirror, produce
     JSONL manifests, and materialize resources to disk or into a ``.zip``
     archive.


Links
~~~~~

   * recount3 @ GitHub_
   * recount3 @ PyPI_
   * Documentation @ Pages_
   * Questions & bug reports @ Issues_


Installation
~~~~~~~~~~~~

The core package requires Python 3.10 or newer and depends on NumPy, pandas,
and SciPy.  Optional extras unlock BiocPy integration and BigWig support.

Install on Linux, Mac OS X
--------------------------

.. code:: bash

   python3 -m pip install recount3

Install on Windows
------------------

.. code:: bash

   py -3 -m pip install recount3

Optional extras
---------------

Install with BiocPy support (``SummarizedExperiment``, ``RangedSummarizedExperiment``,
``GenomicRanges``):

.. code:: bash

   python3 -m pip install "recount3[biocpy]"

Install with BigWig support (``pybigwig``):

.. code:: bash

   python3 -m pip install "recount3[bigwig]"

Install all optional extras:

.. code:: bash

   python3 -m pip install "recount3[biocpy,bigwig]"

Upgrade on Linux, Mac OS X
---------------------------

.. code:: bash

   python3 -m pip install recount3 --upgrade

Upgrade on Windows
------------------

.. code:: bash

   py -3 -m pip install recount3 --upgrade


Quickstart
~~~~~~~~~~

Python API
----------

Discover all resources for a project, stack the gene-level count matrices
across samples, and build a ``RangedSummarizedExperiment``:

.. code:: python

   >>> from recount3 import R3ResourceBundle
   >>>
   >>> # Discover every resource for a human SRA project.
   >>> bundle = R3ResourceBundle.discover(
   ...     organism="human",
   ...     data_source="sra",
   ...     project="SRP009615",
   ... )
   >>>
   >>> # Stack raw gene-count matrices across all samples.
   >>> counts = bundle.only_counts().stack_count_matrices(genomic_unit="gene")
   >>>
   >>> # Build a RangedSummarizedExperiment (requires recount3[biocpy]).
   >>> rse = bundle.to_ranged_summarized_experiment(genomic_unit="gene")

Command-line tool
-----------------

Discover resources, save a JSONL manifest, and download in parallel:

.. code:: bash

   # 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

Stream search output directly into download without an intermediate file:

.. code:: bash

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

.. note:: Read the full documentation on Pages_ for the complete API reference,
          CLI guide, and worked examples.


Dependencies
~~~~~~~~~~~~

Core (installed automatically):

.. code:: text

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

Optional: BiocPy integration (``recount3[biocpy]``):

.. code:: text

   biocframe>=0.7
   genomicranges>=0.8
   summarizedexperiment>=0.6

Optional: BigWig support (``recount3[bigwig]``):

.. code:: text

   pybigwig>=0.3.18


Questions, Feature Requests, and Bug Reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


License
~~~~~~~

This package is distributed under the BSD_ license.


.. _recount3: https://rna.recount.bio
.. _BiocPy: https://github.com/BiocPy
.. _GitHub: https://github.com/MoseleyBioinformaticsLab/recount3
.. _PyPI: https://pypi.org/project/recount3
.. _Pages: https://moseleybioinformaticslab.github.io/recount3/
.. _Issues: https://github.com/MoseleyBioinformaticsLab/recount3/issues
.. _BSD: https://github.com/MoseleyBioinformaticsLab/recount3/blob/main/LICENSE
