GeneXpressor 0.1.5

DESeq2 runner (Python + rpy2) for bulk RNA-seq with auto-discovery, E2E DE, plots, HTML report.

🧬 GeneXpressor

GeneXpressor is a pragmatic DESeq2 runner (Python + rpy2) for bulk RNA-seq differential expression analysis. It automatically discovers your count and metadata files, runs the full DESeq2 workflow, and produces publication-ready plots and a reproducible HTML report — all from a single command.

🚀 Key Features

🔍 Auto-discovery of count + metadata files

🧠 End-to-end DESeq2 analysis with rpy2 integration

📊 Publication-ready visualizations (volcano, MA, heatmap, QC plots)

🧾 Optional HTML report summarizing results

⚙️ Cross-platform (Windows, macOS, Linux)

🧩 Supports both AUTO and manual dataset selection

💡 Lightweight setup – no manual R scripting required

🧰 Requirements Component Version Notes Python ≥ 3.9 64-bit recommended R ≥ 4.0 must be on PATH (R --version) R packages DESeq2, apeglm, ashr, ggplot2, pheatmap, rmarkdown, knitr install via BiocManager Python packages rpy2 ≥ 3.5 installed automatically 🧩 One-time R setup

Run this in your R console:

if(!requireNamespace("BiocManager", quietly=TRUE)) install.packages("BiocManager", repos="https://cloud.r-project.org")

BiocManager::install(c( "DESeq2", "apeglm", "ashr", "ggplot2", "pheatmap", "rmarkdown", "knitr" ), ask=FALSE)

💾 Installation pip install GeneXpressor

or

pip install genexpressor

To confirm:

genexpressor --help

🧩 Input Directory Structure

Your working directory (--parent_dir) should contain:

MyProject/ ├─ counts.csv # genes × samples, first column = gene IDs ├─ metadata.csv # sample info; must include the condition column └─ (optional extra files)

Example metadata.csv:

sample condition S1 Disease S2 Control S3 Disease S4 Control ⚙️ Command-Line Usage 🧠 Example (Windows PowerShell) genexpressor --parent_dir "C:\Users\<username>\Downloads\Deseq2-pkg" --pick AUTO --case_level Disease --control_level Control --alpha 0.05 --lfc_thr 2.0 --top_labels 20 --top_heatmap 50 --make_report true --debug true ` --threads 2

🧪 Example (Linux / macOS) genexpressor
--parent_dir "/path/to/Deseq2-pkg"
--pick AUTO
--case_level Disease
--control_level Control
--alpha 0.05
--lfc_thr 2.0
--top_labels 20
--top_heatmap 50
--make_report true
--debug true
--threads 2

📊 Output Overview

After a successful run, GeneXpressor will create a new results folder inside your working directory containing:

Output file Description deseq2_results.csv Full DESeq2 result table deseq2_significant.csv Filtered DEGs (α- and LFC-based) volcano_plot.png Volcano plot ma_plot.png MA plot heatmap.png Top-gene heatmap QC_*.png Quality-control plots GeneXpressor_Report.html Complete HTML report

Example output structure:

C:\Users<username>\Downloads\Deseq2-pkg
├─ results/ │ ├─ deseq2_results.csv │ ├─ deseq2_significant.csv │ ├─ volcano_plot.png │ ├─ ma_plot.png │ ├─ heatmap.png │ └─ GeneXpressor_Report.html └─ logs/ └─ run.log

🧾 Command Options Flag Description --parent_dir Directory containing counts + metadata --pick Dataset selection (AUTO, ALL, or manual) --case_level / --control_level Condition names --alpha Adjusted p-value cutoff (default 0.05) --lfc_thr log₂ Fold-change threshold --top_labels Genes labeled in volcano plot --top_heatmap Top genes in heatmap --make_report Whether to generate HTML report --threads Parallel worker threads --debug Verbose console logging 🧪 Quick Test python -c "import genexpressor; print(genexpressor.version)" genexpressor --help

Expected output:

0.1.4 genexpressor CLI OK

⚠️ Troubleshooting Issue Cause / Fix ModuleNotFoundError: genexpressor.cli Reinstall the package (pip install --upgrade GeneXpressor) rpy2 or R_HOME errors Ensure R is installed and on PATH (R --version) DESeq2 not found Install via BiocManager::install("DESeq2") Permission denied Run from a directory you own Missing plots / report Check --make_report true and logs 📘 Citation

If you use GeneXpressor in your work, please cite:

Malik, S. (2025). GeneXpressor: Automated DESeq2 runner for bulk RNA-seq via rpy2. PyPI. https://pypi.org/project/GeneXpressor

👤 Author

Sheryar Malik Bioinformatics Scientist 📧 [e-mail]

🔗 GitHub: shari01

📄 License

MIT License © 2025 Sheryar Malik