Metadata-Version: 2.4
Name: bulk-rnaseq-pipeline
Version: 1.1.2
Summary: Interactive, validated and resumable bulk RNA-seq pipeline (HISAT2, featureCounts, StringTie2, DESeq2)
Author: vipin839
License-Expression: MIT
Project-URL: Homepage, https://github.com/vipin839/rnaseq_pipeline
Project-URL: Documentation, https://github.com/vipin839/rnaseq_pipeline/tree/main/docs
Project-URL: Issues, https://github.com/vipin839/rnaseq_pipeline/issues
Keywords: bioinformatics,RNA-seq,DESeq2,HISAT2,featureCounts,transcriptomics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=5.4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# Bulk RNA-seq Pipeline (`rnaseq-pipeline`)

An interactive, terminal-based pipeline for **bulk** RNA-seq: from public accessions (SRA, GEO, ENA) or local FASTQ files
to differential-expression results, plots and an HTML report.

* **Python** does everything up to the gene count matrix: download/import, FASTQ validation, FastQC/MultiQC, the quality gate,
  fastp, reference preparation, HISAT2, BAM validation and QC, strandedness, StringTie2 and featureCounts.
* **R** runs DESeq2 and everything after it: normalisation, tests, up/down genes, and plots.
* Every stage **validates its outputs independently** (for example, FASTQ reads = HISAT2 reads = BAM primary records;
  count-matrix column sums = featureCounts assigned reads; up/down tables re-derived from the full result table).
* **Checkpoints** make interrupted runs resumable. A changed input, output or scientific setting re-runs exactly the
  affected stages.
* Scientific decisions (trimming, strandedness, experimental design) are **never guessed**; you confirm each one, with
  an explanation.

> **New to RNA-seq or to this tool?** Read the illustrated **User Guide and Learning Book**
> ([PDF](docs/RNAseq_Pipeline_User_Guide.pdf) · [Word](docs/RNAseq_Pipeline_User_Guide.docx)): installation step by
> step, every stage and tool explained in plain language with flowcharts, how to read the results and plots, a worked
> example, troubleshooting, a glossary and how to cite. No programming knowledge needed.

```
DATA (SRA / GEO / ENA / local, or search NCBI) -> FASTQ validation -> FastQC + MultiQC -> quality gate
  -> [fastp -> validation -> FastQC + MultiQC]  (only if you decide to trim)
  -> reference (catalog, any organism from NCBI, or your own FASTA + GTF; validated; HISAT2 index)
  -> HISAT2 | samtools sort -> BAM validation -> BAM QC -> strandedness (inferred, confirmed)
  -> StringTie2 (transcript TPM)   and   featureCounts (gene counts)      <- independent
  -> count matrix -> experimental design (you confirm) -> DESeq2 -> plots -> validated HTML report + manifest
```

## Install

```bash
pipx install git+https://github.com/vipin839/rnaseq_pipeline.git         # the command
mamba env create -f "$(rnaseq-pipeline --runtime-env tools)"               # FastQC, HISAT2, samtools, ...
mamba env create -f "$(rnaseq-pipeline --runtime-env r)"                   # R + DESeq2
rnaseq-pipeline --check                                                    # functional health check
```

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for conda setup, the Bioconda recipe (one-command install after it
is published), user settings and upgrading from 1.0.0.

## Use

```bash
rnaseq-pipeline                              # interactive menu
rnaseq-pipeline --project ~/rnaseq_projects/RNAseq_MyStudy   # resume a project
rnaseq-pipeline --validate-project DIR       # re-verify a project: PROJECT HEALTH PASS / WARNING / FAIL
rnaseq-pipeline --dry-run --project DIR      # show what would run, execute nothing
rnaseq-pipeline --check                      # installation health check
```

## What is supported

| | Status | Notes |
|---|---|---|
| Bulk RNA-seq, paired-end or single-end, Illumina | **Supported** | the layout must be the same for all samples in a project |
| Unstranded / forward / reverse libraries | **Supported** | inferred with RSeQC and confirmed; all three tested end to end |
| Human, mouse, yeast (catalog); any organism with an NCBI GTF; custom FASTA + GTF | **Supported** | genome and annotation compatibility is checked (names, lengths, assembly) |
| Bacteria (CDS-only NCBI annotation) | **Supported** | counts CDS; StringTie2 skipped; tested with E. coli UTI89 |
| Designs `~ condition`, `~ batch + condition`, several groups/contrasts | **Supported** | ≥2 biological replicates per group; confounding refused |
| Lanes / technical replicates | **Supported** | summed on request |
| Time course (LRT), interactions, continuous covariates | **Not supported** | planned |
| Mixed layouts or organisms in one project | **Refused** | use separate projects |
| Single-cell RNA-seq (10x, Drop-seq, Smart-seq, …) | **Refused** | detected from metadata and read structure; use Cell Ranger / STARsolo / alevin-fry |
| Human-scale data on a small machine | **Partially** | the index is built without splice sites below ~160 GB RAM (sites are given at alignment); ~8 GB RAM needed to align |
| GO / Reactome enrichment | **Partially** | optional; needs extra R packages; not part of the tested core |
| macOS, Windows (native) | **Not supported** | Linux and WSL2 only |
| Web interface, HPC schedulers, containers | **Not supported** | future versions |

## Documentation

| Document | Contents |
|---|---|
| [User Guide and Learning Book (PDF)](docs/RNAseq_Pipeline_User_Guide.pdf) / [Word](docs/RNAseq_Pipeline_User_Guide.docx) | complete illustrated guide for users: setup, workflow with flowcharts, every tool, result interpretation, worked example, troubleshooting, glossary, citation |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | install options, runtime layer, user settings, upgrading |
| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | step-by-step use, menus, decisions, resuming, logs |
| [docs/PIPELINE_METHODS.md](docs/PIPELINE_METHODS.md) | what each stage does, parameters, thresholds, validation |
| [docs/VERIFICATION_MATRIX.md](docs/VERIFICATION_MATRIX.md) | requirement → code → tests → evidence → status |
| [docs/TESTING.md](docs/TESTING.md) | test suites, synthetic truth data, real-data evidence |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | errors and fixes |
| [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) | architecture and extension points |
| [docs/RELEASE.md](docs/RELEASE.md) | release procedure (tag, PyPI, Bioconda) |
| [CHANGELOG.md](CHANGELOG.md) | version history |

## How to cite

> Vipin (2026). rnaseq-pipeline: an interactive, validated and resumable bulk RNA-seq pipeline (version 1.1.2)
> [Computer software]. GitHub. https://github.com/vipin839/rnaseq_pipeline

Please also cite the tools the pipeline runs (FastQC, MultiQC, fastp, HISAT2, SAMtools, RSeQC, StringTie2,
featureCounts, DESeq2, apeglm). Full references and an example methods paragraph are in chapter 22 of the
[User Guide](docs/RNAseq_Pipeline_User_Guide.pdf).

## Developer and contact

Developed and maintained by **Vipin** ([github.com/vipin839](https://github.com/vipin839/)).

* Website: [www.vipin.social](https://www.vipin.social/)
* E-mail: [sainivipin839@gmail.com](mailto:sainivipin839@gmail.com)
* Questions and bug reports: [GitHub issues](https://github.com/vipin839/rnaseq_pipeline/issues)

License: MIT.
