Skip to content

Commit 7e167a2

Browse files
tylergross97tylergross97
authored
Merge pull request #2 from tylergross97/seqera-ai/20251219-201605-enable-stub-mode-testing
Improve README with comprehensive documentation
2 parents 24dec83 + 17f9901 commit 7e167a2

1 file changed

Lines changed: 269 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 269 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,27 @@
11
# Xengsort Nextflow Pipeline
2-
A Nextflow pipeline to perform deconvolution of contaminant sequencing reads using Xengsort by Zentgraf and Rahmann (2021)
32

4-
This tool is assay-agnostic! Meaning you can provide fastq.gz files generated from WES/WGS, RNAseq, ATACseq, etc.
3+
[![Nextflow](https://img.shields.io/badge/nextflow%20DSL2-%E2%89%A525.04.0-23aa62.svg)](https://www.nextflow.io/)
4+
[![run with docker](https://img.shields.io/badge/run%20with-docker-0db7ed?labelColor=000000&logo=docker)](https://www.docker.com/)
5+
[![run with singularity](https://img.shields.io/badge/run%20with-singularity-1d355c.svg?labelColor=000000)](https://sylabs.io/docs/)
6+
7+
A Nextflow DSL2 pipeline for separating human and mouse sequencing reads from Patient-Derived Xenograft (PDX) samples using [Xengsort](https://gitlab.com/genomeinformatics/xengsort) (Zentgraf and Rahmann, 2021).
8+
9+
## 🎯 Overview
10+
11+
When tumor samples from PDX models (human tumors grown in immunocompromised mice) are sequenced, the resulting data contains a mixture of:
12+
- 🧬 **Human reads** (from the transplanted tumor)
13+
- 🐭 **Mouse reads** (from the host tissue)
14+
15+
This pipeline cleanly separates these reads, providing contamination-free human sequences for downstream analysis.
16+
17+
### ✨ Key Features
18+
19+
- **Assay-agnostic**: Works with WGS, WES, RNA-seq, ATAC-seq, ChIP-seq, and other NGS data
20+
- **Fast & accurate**: Leverages Xengsort's k-mer based classification
21+
- **Quality control**: Integrated FASTP for read trimming and QC
22+
- **Comprehensive reports**: MultiQC aggregation and contamination statistics
23+
- **Production-ready**: Docker and Singularity support for reproducibility
24+
- **NSG-optimized**: Compatible with NSG-adapted mouse reference genome
525

626
## Workflow
727
```mermaid
@@ -27,54 +47,269 @@ flowchart TB
2747
end
2848
```
2949

30-
## Running Pipeline
50+
## 🚀 Quick Start
51+
52+
Run the pipeline directly from GitHub (no cloning required):
3153

32-
Instead of cloning the entire repository, you can simply run v.1.0.0 from the command line
3354
```bash
34-
nextflow run tylergross97/nextflow_xengsort main.nf \
35-
--input /path/to/samplesheet.csv \
36-
--outdir_base /path/to/output/directory/base \
37-
--hg38_fasta /path/to/human/reference/genome.fa \
38-
--nsg_fasta /path/to/nsg_mouse/reference/genome.fa \
39-
-profile docker_or_singularity
55+
nextflow run tylergross97/nextflow_xengsort \
56+
--input samplesheet.csv \
57+
--outdir_base results \
58+
--hg38_fasta /path/to/GRCh38.fa \
59+
--nsg_fasta /path/to/mm10.nsgSpike.fa \
60+
-profile docker
4061
```
41-
### Inputs
4262

43-
#### Samplesheet
44-
```bash
63+
### Prerequisites
64+
65+
- **Nextflow** ≥25.04.0 ([installation guide](https://www.nextflow.io/docs/latest/getstarted.html))
66+
- **Docker** or **Singularity** for containerization
67+
- **Reference genomes**: Human (GRCh38/hg38) and Mouse (see below)
68+
## 📥 Input Requirements
69+
70+
### 1. Samplesheet (CSV format)
71+
72+
Create a comma-separated file with three columns:
73+
74+
| Column | Description |
75+
|--------|-------------|
76+
| `sample` | Unique sample identifier |
77+
| `fastq1` | Path to R1 FASTQ file (gzipped) |
78+
| `fastq2` | Path to R2 FASTQ file (gzipped) |
79+
80+
**Example:**
81+
```csv
4582
sample,fastq1,fastq2
46-
sample1,/path/to/sample1_R1.fastq.gz,/path/to/sample1_R2.fastq.gz
47-
sample2,/path/to/sample2_R1.fastq.gz,/path/to/sample2_R2.fastq.gz
83+
PDX_001,/data/PDX_001_R1.fastq.gz,/data/PDX_001_R2.fastq.gz
84+
PDX_002,/data/PDX_002_R1.fastq.gz,/data/PDX_002_R2.fastq.gz
85+
PDX_003,/data/PDX_003_R1.fastq.gz,/data/PDX_003_R2.fastq.gz
4886
```
4987

50-
#### Reference genomes
51-
In the case of PDX models with NSG mice, it is recommended to use the NSG-adapted mouse reference genome from [Hynds et al. (2024)](https://www.nature.com/articles/s41467-024-47547-3) by running the following bash command:
88+
> **Note**: Files must be paired-end Illumina reads in gzipped FASTQ format
89+
90+
### 2. Reference Genomes
91+
92+
#### Human Reference (Required)
93+
- **GRCh38/hg38** (recommended) or GRCh37/hg19
94+
- Download from [NCBI](https://www.ncbi.nlm.nih.gov/genome/guide/human/) or [UCSC](https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/)
95+
96+
#### Mouse Reference (Required)
97+
98+
For **NSG mice** (most common PDX host), use the NSG-adapted reference from [Hynds et al. (2024)](https://www.nature.com/articles/s41467-024-47547-3):
99+
52100
```bash
53-
curl -O https://zenodo.org/records/10304175/files/nsg_adapted_reference.zip?download=1
54-
mv 'nsg_adapted_reference.zip?download=1' nsg_adapted_reference.zip
101+
# Download NSG-adapted mouse reference
102+
wget https://zenodo.org/records/10304175/files/nsg_adapted_reference.zip
55103
unzip nsg_adapted_reference.zip
56104
cd nsgReference/
57-
ls
105+
106+
# Use mm10.nsgSpike.fa for --nsg_fasta parameter
107+
```
108+
109+
For **other mouse strains**, use standard mm10/mm39 from [NCBI](https://www.ncbi.nlm.nih.gov/genome/guide/mouse/) or [UCSC](https://hgdownload.soe.ucsc.edu/goldenPath/mm10/bigZips/).
110+
111+
## 📤 Output Files
112+
113+
The pipeline generates the following output structure:
114+
115+
```
116+
results/
117+
├── fastp/
118+
│ ├── {sample}_trimmed_1.fastq.gz # Human-only R1 reads (use these!)
119+
│ ├── {sample}_trimmed_2.fastq.gz # Human-only R2 reads (use these!)
120+
│ ├── {sample}_fastp.json # FASTP QC metrics
121+
│ └── {sample}_fastp.html # FASTP QC report
122+
├── xengsort/
123+
│ ├── {sample}.xengsort.txt # Per-sample classification
124+
│ ├── xengsort_summary.csv # Aggregate contamination stats
125+
│ └── xengsort_index.* # Index files (can be reused)
126+
└── multiqc/
127+
└── multiqc_report.html # Aggregated QC report
128+
```
129+
130+
### Key Output Files
131+
132+
| File | Description | Use For |
133+
|------|-------------|---------|
134+
| `fastp/*_trimmed_{1,2}.fastq.gz` | **Clean human reads** | Downstream analysis (variant calling, RNA-seq, etc.) |
135+
| `xengsort/xengsort_summary.csv` | Contamination statistics | QC and sample evaluation |
136+
| `multiqc/multiqc_report.html` | Comprehensive QC report | Overall run assessment |
137+
138+
### Downstream Integration
139+
140+
The clean human reads can be directly used as input for:
141+
- **Variant calling**: [nf-core/sarek](https://nf-co.re/sarek)
142+
- **RNA-seq analysis**: [nf-core/rnaseq](https://nf-co.re/rnaseq)
143+
- **ATAC-seq analysis**: [nf-core/atacseq](https://nf-co.re/atacseq)
144+
- **Custom pipelines**: Any analysis requiring human-only reads
145+
146+
## 🧪 Testing
147+
148+
Test the pipeline installation with a minimal dataset:
149+
150+
```bash
151+
nextflow run tylergross97/nextflow_xengsort -profile test,docker
152+
```
153+
154+
This runs with:
155+
- Pre-configured test data (3 small samples)
156+
- Reduced memory requirements
157+
- ~5 minute runtime
158+
- Outputs to `results_test/` directory
159+
160+
## ⚙️ Parameters
161+
162+
### Required Parameters
163+
164+
| Parameter | Description |
165+
|-----------|-------------|
166+
| `--input` | Path to samplesheet CSV file |
167+
| `--outdir_base` | Base output directory |
168+
| `--hg38_fasta` | Path to human reference genome (FASTA) |
169+
| `--nsg_fasta` | Path to mouse reference genome (FASTA) |
170+
171+
### Optional Parameters
172+
173+
| Parameter | Default | Description |
174+
|-----------|---------|-------------|
175+
| `--outdir_references` | `${outdir_base}/references` | Reference output directory |
176+
| `--outdir_fastp` | `${outdir_base}/fastp` | FASTP output directory |
177+
| `--outdir_xengsort` | `${outdir_base}/xengsort` | Xengsort output directory |
178+
| `--outdir_multiqc` | `${outdir_base}/multiqc` | MultiQC output directory |
179+
180+
### Profiles
181+
182+
Choose a container platform:
183+
184+
```bash
185+
# Docker (recommended for local systems)
186+
-profile docker
187+
188+
# Singularity (recommended for HPC)
189+
-profile singularity
190+
191+
# Test with minimal data
192+
-profile test,docker
58193
```
59-
- You can then specify the path of mm10.nsgSpike.fa for the --nsg_fasta command line argument
60194

61-
### Outputs
62-
You will find the trimmed, human-only filtered reads in ${outdir_base}/fastp/human_trimmed_{1,2}.fastq.gz - these can be then be used as input into pipelines that require uncontaminated reads, such as nf-core/sarek or nf-core/rnaseq
195+
## 💻 Usage Examples
63196

64-
If you want to explore mouse contamination, refer to ${outdir_base}/xengsort/xengsort_summary.csv, which will contain sample-level contamination information
197+
### Basic Usage
65198

66-
### Testing
67-
To test pipeline with a minimal dataset, run pipeline with:
68199
```bash
69-
nextflow run tylergross97/nextflow_xengsort -profile test,docker_or_singularity
200+
nextflow run tylergross97/nextflow_xengsort \
201+
--input samplesheet.csv \
202+
--outdir_base ./pdx_results \
203+
--hg38_fasta /references/GRCh38.fa \
204+
--nsg_fasta /references/mm10.nsgSpike.fa \
205+
-profile docker
70206
```
71-
The author parameters are predefined if running test profile
72207

73-
## Citations
74-
If you use this pipeline in your work, please cite: [Tyler Gross] (2025). Xengsort Nextflow Pipeline [Computer software]. https://github.com/tylergross97/nextflow_xengsort
208+
### HPC with Singularity
209+
210+
```bash
211+
nextflow run tylergross97/nextflow_xengsort \
212+
--input samplesheet.csv \
213+
--outdir_base /scratch/user/pdx_analysis \
214+
--hg38_fasta /refs/hg38.fa \
215+
--nsg_fasta /refs/mm10_nsg.fa \
216+
-profile singularity \
217+
-resume
218+
```
219+
220+
### Resume Failed Run
221+
222+
```bash
223+
nextflow run tylergross97/nextflow_xengsort \
224+
--input samplesheet.csv \
225+
--outdir_base ./results \
226+
--hg38_fasta /refs/hg38.fa \
227+
--nsg_fasta /refs/mm10.fa \
228+
-profile docker \
229+
-resume # Continues from where it stopped
230+
```
231+
232+
## 📊 Performance & Resource Requirements
233+
234+
### Typical Runtime
235+
- **Small dataset** (3 samples, ~10M reads/sample): ~30 minutes
236+
- **Medium dataset** (10 samples, ~50M reads/sample): ~3-5 hours
237+
- **Large dataset** (50 samples, ~100M reads/sample): ~12-24 hours
238+
239+
*Note: Runtime varies based on CPU cores and read depth*
240+
241+
### Memory Requirements
242+
- **FASTP**: 2-4 GB per sample
243+
- **XENGSORT_INDEX**: 8-16 GB (one-time, reusable)
244+
- **XENGSORT_CLASSIFY**: 32 GB per sample (scales with retries)
245+
- **Recommended minimum**: 32 GB RAM for typical runs
246+
247+
## 🐛 Troubleshooting
248+
249+
### Common Issues
250+
251+
**Issue**: `xengsort classify` fails with memory error
252+
- **Solution**: Increase memory in `nextflow.config` or use `-resume` to retry with more memory
253+
254+
**Issue**: Reference genome files not found
255+
- **Solution**: Verify absolute paths and file existence for `--hg38_fasta` and `--nsg_fasta`
256+
257+
**Issue**: Docker/Singularity permission errors
258+
- **Solution**: Ensure Docker daemon is running and user has appropriate permissions
259+
260+
**Issue**: Pipeline hangs or stalls
261+
- **Solution**: Check disk space and network connectivity; use `-resume` to continue
262+
263+
### Getting Help
264+
265+
- **Issues**: [GitHub Issues](https://github.com/tylergross97/nextflow_xengsort/issues)
266+
- **Questions**: Open a discussion or issue on GitHub
267+
268+
## 🤝 Contributing
269+
270+
Contributions are welcome! Please:
271+
1. Fork the repository
272+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
273+
3. Commit your changes (`git commit -m 'Add amazing feature'`)
274+
4. Push to the branch (`git push origin feature/amazing-feature`)
275+
5. Open a Pull Request
276+
277+
## 📜 Citations
278+
279+
### Pipeline
280+
281+
If you use this pipeline in your research, please cite:
282+
283+
> **Gross, T.** (2025). *Xengsort Nextflow Pipeline* [Computer software]. https://github.com/tylergross97/nextflow_xengsort
284+
285+
### Dependencies
75286

76287
This pipeline uses the following tools that should be cited independently:
77-
1. Di Tommaso, P., Chatzou, M., Floden, E. W., Barja, P. P., Palumbo, E., & Notredame, C. (2017). Nextflow enables reproducible computational workflows. Nature biotechnology, 35(4), 316-319.
78-
2. Chen, S., Zhou, Y., Chen, Y., & Gu, J. (2018). fastp: an ultra-fast all-in-one FASTQ preprocessor. Bioinformatics, 34(17), i884-i890.
79-
3. Hynds, R. E., Huebner, A., Pearce, D. R., Hill, M. S., Akarca, A. U., Moore, D. A., ... & Swanton, C. (2024). Representation of genomic intratumor heterogeneity in multi-region non-small cell lung cancer patient-derived xenograft models. Nature communications, 15(1), 4653.
80-
4. Zentgraf, J., & Rahmann, S. (2021). Fast lightweight accurate xenograft sorting. Algorithms for Molecular Biology, 16(1), 2.
288+
289+
1. **Nextflow**
290+
Di Tommaso, P., Chatzou, M., Floden, E. W., Barja, P. P., Palumbo, E., & Notredame, C. (2017). Nextflow enables reproducible computational workflows. *Nature Biotechnology*, 35(4), 316-319. https://doi.org/10.1038/nbt.3820
291+
292+
2. **Xengsort**
293+
Zentgraf, J., & Rahmann, S. (2021). Fast lightweight accurate xenograft sorting. *Algorithms for Molecular Biology*, 16(1), 2. https://doi.org/10.1186/s13015-021-00181-w
294+
295+
3. **fastp**
296+
Chen, S., Zhou, Y., Chen, Y., & Gu, J. (2018). fastp: an ultra-fast all-in-one FASTQ preprocessor. *Bioinformatics*, 34(17), i884-i890. https://doi.org/10.1093/bioinformatics/bty560
297+
298+
4. **MultiQC**
299+
Ewels, P., Magnusson, M., Lundin, S., & Käller, M. (2016). MultiQC: summarize analysis results for multiple tools and samples in a single report. *Bioinformatics*, 32(19), 3047-3048. https://doi.org/10.1093/bioinformatics/btw354
300+
301+
5. **NSG Reference** (if used)
302+
Hynds, R. E., Huebner, A., Pearce, D. R., Hill, M. S., Akarca, A. U., Moore, D. A., ... & Swanton, C. (2024). Representation of genomic intratumor heterogeneity in multi-region non-small cell lung cancer patient-derived xenograft models. *Nature Communications*, 15(1), 4653. https://doi.org/10.1038/s41467-024-47547-3
303+
304+
## 📄 License
305+
306+
This pipeline is released under the MIT License. See `LICENSE` file for details.
307+
308+
## 👤 Author
309+
310+
**Tyler Gross**
311+
- GitHub: [@tylergross97](https://github.com/tylergross97)
312+
313+
---
314+
315+
**⭐ If you find this pipeline useful, please consider starring the repository!**

0 commit comments

Comments
 (0)