A Nextflow pipeline for allele frequency analysis from pooled Illumina sequencing data
Platform note: PoolSeqFlow is developed and tested on Linux and macOS. Windows is not supported — the resume logic relies on symbolic links and Unix-style paths that are not compatible with native Windows filesystems.
PoolSeqFlow takes raw FASTQ files and a reference genome and gives back allele frequency tables. It automates quality control, adapter trimming with composition-aware clipping, alignment, BAM post-processing, variant calling and VCF-to-frequency conversion, with optional annotation.
Pool-seq sequences many individuals together, so the unit of analysis is not a genotype but a frequency — and that difference runs through every stage. Multiallelic sites are preserved rather than collapsed, VCFs are re-encoded so the most-read allele is the reference, and the minimum credible frequency is derived from your pool size and ploidy instead of a fixed cutoff. See When to use PoolSeqFlow for what the design assumes about your data.
Raw FASTQ reads
│
▼
[Step 0] Verify environment, parameters and folder structure
│
▼
[Step 1] Build reference dictionaries (BWA, SAMtools, SnpEff)
│
▼
[Step 2] QC & trimming (FastQC → Trim Galore → composition-aware clipping)
│
▼
[Step 3] Alignment (BWA-MEM)
│
▼
[Step 4] BAM cleanup (name-sort → fixmate → coord-sort → markdup → addRG → filter → index)
│
▼
[Step 5] Alignment & coverage reports (BAMtools, SAMtools)
│
▼
[Step 6] Variant calling (BCFtools mpileup + call)
│
├────────────────────────────────────────────┐
▼ ▼
[Step 7] VCF → allele frequency tables [Step 8] Annotation (SnpEff, optional)
Requires Linux or macOS and conda. Every bioinformatics tool is installed for you into an isolated environment, pinned to an exact build.
# 1. Download the latest release
curl -LO https://github.com/ozankiratli/PoolSeqFlow/releases/latest/download/PoolSeqFlow.tar.gz
tar -xzf PoolSeqFlow.tar.gz
cd PoolSeqFlow-*/
# 2. Create your configuration
cp parameters.config.template parameters.config
# then edit it: mainDir, projectDir, readPattern, referenceFile, poolSize, diploidy# 3. Build and verify the environment
./PoolSeqFlow install
# 4. Run — this is also the resume command
./PoolSeqFlow runYour project directory needs a Data/ folder of FASTQs, a gzipped reference, and an RGTags.csv. Copy RGTags.csv.template and fill it in — it is not only metadata, it decides which FASTQ pairs count as one sample and the order your result columns come out in.
Full walkthrough: Install and Quick Start.
Configure through
parameters.configonly. PoolSeqFlow does not accept command-line parameter overrides, and./PoolSeqFlowdeliberately rejects any argument beyond a single subcommand. A run is therefore fully described by a file you can version, diff and publish. It also avoids a silent failure: Nextflow delivers--paramvalues as strings, so--annotate falsesets the string"false", which Groovy evaluates as true.
| Command | Description |
|---|---|
./PoolSeqFlow install | Create the conda environment, then verify it |
./PoolSeqFlow check | Verify an existing installation — tools, helpers, config |
./PoolSeqFlow run | Start — or resume — the pipeline |
./PoolSeqFlow migrate_config | Carry an older parameters.config onto the current template |
./PoolSeqFlow clean | Remove Nextflow work directories |
./PoolSeqFlow reset | Remove all progress and start fresh (typed confirmation required) |
./PoolSeqFlow version | Print the installed version |
./PoolSeqFlow cite | Print how to cite this copy, and which DOI to use |
./PoolSeqFlow uninstall | Remove the conda environment |
There is no -resume flag. Every step checks whether its outputs already exist in permanent storage and skips itself if they do, so run both starts and resumes — and that survives job timeouts, reboots and work/ cleanups. Why →
| When to use it | What pooling buys and costs, and what the pipeline assumes about your design |
| Design decisions | Why configuration is a file, why resume is filesystem-based, what each choice costs |
| The filter chain | All eight filters in order, what each removes, and how to tune them |
| Interpreting results | The frequency table format, and the mistakes that are easy to make reading it |
| Configuration | Every parameter, sorted by whether it changes your results |
| Read groups | RGTags.csv, and why SM decides what counts as a sample |
| Pipeline steps | Steps 0–8 in detail |
| Upgrading | Your parameters.config is never touched by an update — read this first |
| Troubleshooting | Errors by symptom |
Your installed copy prints its own citation, with the version filled in:
./PoolSeqFlow citeCite the version you actually ran, not the newest one. Zenodo issues a separate DOI for every release, and results depend on which release produced them — filters, defaults and parameter names have all changed between versions. Step 0 records the versions that have run in a project in .poolseqflow_versions, mirrored into Output/run_parameters.txt.
10.5281/zenodo.19245611 is the all-versions DOI: it always resolves to the newest release. Use it to refer to the software in general, and a version DOI when reporting results. Details →
Apache 2.0 — see LICENSE. The tools PoolSeqFlow invokes carry their own licenses.
Ozan L. Z. Kiratli · @ozankiratli · Issues