Repository navigation
Nextflow Genetic Variation Analysis Workflow
Engine:
Nextflow· Workflow ID:genetic_variation_analysis· Path in repo:nextflow/workflows/genetic_variation_analysis/
This workflow identifies the genetic variants carried by a set of short-read DNA sequencing samples and tests them for statistical association with measured phenotypic traits. It assumes single-end or paired-end sequencing reads, a reference genome FASTA, a matching GTF/GFF annotation and a table of phenotype values per sample. The pipeline orchestrates the OmicsBox variant-analysis chain end to end — read quality assessment, adapter and quality trimming, alignment to the reference genome with BWA, variant calling with BCFtools, filtering of the raw call set, genotype phasing and imputation with Beagle, and a genome-wide association study — alongside a parallel branch that annotates the filtered variants with their predicted functional effect on the annotated features.
flowchart TD
%% ---- Inputs ----
IN1[/"FASTQ reads"/]:::input
IN2[/"QC adapters and<br/>contaminants"/]:::input
IN3[/"Trimming adapters"/]:::input
IN4[/"Reference genome<br/>FASTA"/]:::input
IN5[/"Sample groups"/]:::input
IN6[/"Phenotype traits"/]:::input
IN7[/"Kinship and<br/>covariates"/]:::input
IN8[/"Genome annotation<br/>GTF or GFF"/]:::input
%% ---- Processes ----
P01["FASTQC_RAW"]:::chart
P02["TRIMMOMATIC"]:::omicsbox
P03["FASTQC_POST"]:::chart
P04["BWA"]:::omicsbox
P05["BCFTOOLS"]:::omicsbox
P06["VARIANT_FILTERING"]:::omicsbox
P07["BEAGLE"]:::omicsbox
P08["GWAS"]:::omicsbox
P09["VARIANT_ANNOTATION"]:::omicsbox
%% ---- Data flow ----
IN1 --> P01
IN1 --> P02
IN2 -.-> P01
IN2 -.-> P03
IN3 -.-> P02
P02 --> P03
P02 --> P04
IN4 --> P04
P04 --> P05
IN4 --> P05
IN5 -.-> P05
P05 --> P06
P06 --> P07
P07 --> P08
IN6 --> P08
IN7 -.-> P08
P06 --> P09
IN8 --> P09
IN4 --> P09
classDef input fill:#e8f4fd,stroke:#1f77b4,stroke-width:1px;
classDef omicsbox fill:#fff3e0,stroke:#e67e22,stroke-width:1px;
classDef chart fill:#f4ecf7,stroke:#8e44ad,stroke-width:1px;
-
FASTQC_RAW — Assesses the quality of the untrimmed reads with
omicsbox fastqc, screening them against user-supplied adapter and contaminant sequences when those files are provided. Its report is a standalone diagnostic: no later step consumes it, so it can be inspected while the rest of the pipeline is still running. -
TRIMMOMATIC — Cleans the raw reads with
omicsbox trimmomatic, applying the adapter-removal, edge-trimming, quality-trimming and read-filtering stages enabled in the configuration. Emits the trimmed reads consumed byFASTQC_POSTandBWA, a trimming report, and — for paired-end input — the reads whose mate was discarded, kept apart in their own subfolder.-
FASTQC_POST — Re-runs
omicsbox fastqcon the trimmed reads so the effect of trimming can be compared againstFASTQC_RAW. Like the raw-read assessment, it is a standalone diagnostic.
-
FASTQC_POST — Re-runs
-
BWA — Aligns the trimmed reads to the reference genome with
omicsbox bwa, under the configured seeding, scoring and output-filtering options, and tags every alignment with a read group when the configuration asks for one. Emits the sorted alignments consumed byBCFTOOLS, together with an alignment report and its charts. -
BCFTOOLS — Calls SNPs and indels from the alignments against the reference genome with
omicsbox variantcalling-multipackage, under the configured duplicate-removal, pileup and calling options, and optionally assigns the samples to populations so that Hardy-Weinberg expectations are evaluated per population. Emits the raw variant call set consumed byVARIANT_FILTERING, plus a report and its charts in the configured chart format. -
VARIANT_FILTERING — Discards unreliable calls from the raw call set with
omicsbox variant-filtering-freebayes, applying the configured quality, depth, mapping-quality, missingness and minor-allele-frequency criteria. Emits the filtered call set — consumed by bothBEAGLEandVARIANT_ANNOTATION— plus a report and its charts. -
BEAGLE — Resolves the filtered genotypes into haplotypes and imputes the ungenotyped markers
with
omicsbox beagle, running the configured burn-in and phasing iterations over sliding windows of the genome and estimating the effective population size unless one is supplied. Emits the phased and imputed genotypes consumed byGWAS, plus a report. -
GWAS — Tests every retained marker for association with the phenotypic traits using
omicsbox gwas, after its own round of site and sample filtering, the configured linkage-disequilibrium pruning and the configured phenotype standardisation. Population structure is accounted for through a kinship matrix and a covariate matrix, each either computed internally by the configured method or read from a supplied file, and the association model itself is a configuration option. Emits the association results, a summary report and — when phenotype normalisation is enabled — the transformed trait values. -
VARIANT_ANNOTATION — Annotates the filtered variants with their predicted functional effect on
the annotated features using
omicsbox variant-annotation, reading the genome FASTA and the GTF/GFF annotation alongside the call set. It branches offVARIANT_FILTERINGrather than continuing fromBEAGLEby design: phasing rewrites the variant file's contig headers and drops unplaced scaffolds, so the phased genotypes no longer describe the same reference and OmicsBox rejects them. Emits the variant annotation table, a report and a chart of the annotated variant types.
A run needs reads, a reference genome, a matching annotation and a table of phenotype values. Setting both read parameters, or neither, aborts the run before any OmicsBox job is launched, as does leaving out any of the other three required files. The remaining inputs are optional, and each is read only when the step that consumes it is configured to use it.
| Parameter | Format | Required | Description |
|---|---|---|---|
input_single_end / input_paired_end
|
FASTQ (.fastq / .fq / .fastq.gz / .fq.gz) |
✅ | Glob matching the read files of every sample — set exactly one of the two, whichever matches the library layout. Paired-end mates are paired by filename, so those files must follow one consistent convention, declared through the upstream_pattern and downstream_pattern settings. |
input_fasta |
FASTA (.fasta / .fa / .fna, plain or .gz) |
✅ | Reference genome sequence, shared by BWA, BCFTOOLS and VARIANT_ANNOTATION, so variants are called and annotated against the exact assembly the reads were aligned to. An Ensembl genome release is recommended. |
variant_annotation.annotation |
GTF / GFF (.gtf / .gff / .gff3, plain or .gz) |
✅ | Annotation of the reference genome, read only by VARIANT_ANNOTATION to resolve the functional effect of each variant. Must describe the same species and assembly version as input_fasta. |
gwas.input_pheno |
Tab-delimited text (.tsv / .txt) |
✅ | Trait table read by GWAS. Its first column holds the sample names, which have to match the sample names carried by the genotypes; every further column is a trait to test. A header line is required. |
trimmomatic.adapters |
FASTA (.fasta / .fa / .faa / .fsa / .ffn / .fnn / .fna / .txt) |
⬜ | Custom adapter sequences for TRIMMOMATIC, relevant when that step is configured to remove adapters from a custom list rather than a built-in one. |
fastqc.adapters |
FASTA (.fasta / .fsa / .fa / .fna / .fas) |
⬜ | Custom adapter sequences to screen for, consumed by both FASTQC_RAW and FASTQC_POST. Supplying the file enables adapter screening in those steps. |
fastqc.contaminants |
FASTA (.fasta / .fsa / .fa / .fna / .fas) |
⬜ | Custom contaminant sequences to screen for, consumed by both FASTQC_RAW and FASTQC_POST. Supplying the file enables contaminant screening in those steps. |
bcftools.group_experiment |
Tab-delimited text (.tsv / .txt) |
⬜ | Sample-to-group mapping consumed by BCFTOOLS, with the sample names in the first column and the population each one belongs to in the second. Read only when that step's --use-groups flag is also enabled — supplying the path on its own has no effect. |
gwas.kinship |
Tab-delimited text (.tsv / .txt) |
⬜ | Precomputed kinship matrix for GWAS — the all-versus-all table of relatedness between samples. Read only when that step's --use-kinship flag is also enabled, which at the same time makes the internal kinship-construction options irrelevant. |
gwas.covariate_matrix |
Tab-delimited text (.tsv / .txt) |
⬜ | Sample metadata table from which GWAS derives its covariate matrix through a dimension-reduction algorithm — not a ready-made covariate matrix. Read only when that step's --use-covariate-matrix flag is also enabled, which at the same time replaces the internally computed principal-component covariates. |
Phenotype table format
Sample FloweringTime PlantHeight
sample1 42.0 118.5
sample2 45.5 124.0
sample3 38.0 109.2
sample4 51.0 131.7
Note
The sample names in the first column of the phenotype table are what tie the association test back
to the reads: BWA derives them from the read filenames when it writes the read-group header, and
they travel through the alignments into the variant file GWAS reads. Any TRIMMOMATIC option that
renames the trimmed read files — an output prefix, for instance — therefore renames the samples as
well and has to be mirrored in the phenotype table, or no sample matches and the association test
has nothing to test.
This workflow follows the repository's self-documenting configuration strategy: you do not need to memorise parameter names, consult a reference table, or learn the OmicsBox CLI syntax. Every customisable option is already declared, grouped, and documented with inline comments inside the workflow's own configuration file.
To configure a run:
- Generate your own copy of the configuration file — Step 1 of Execution below.
- Open it in any text editor and read the inline comments; each option lists its accepted values and its default.
- Fill in the values you need and comment / uncomment the flags you want to enable or disable.
- Leave everything else untouched — the entries you do not change fall back to the tested defaults.
Tip
Keep your customised configuration file next to your project data and under version control. It is a complete, human-readable record of how a run was parameterised, which is all you need to reproduce it later.
Before running this workflow for the first time, complete the environment setup described on the central Nextflow Execution & Configuration page.
Two ways to run this workflow are supported. Option A is recommended when you want to inspect or modify the pipeline code; Option B runs the published version straight from GitHub with no manual clone.
Assuming you have already cloned the repository and navigated to its root directory:
Step 1 — Dump the configuration file
nextflow run nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf --dump_configThis copies the self-documenting template to ./genetic_variation_analysis.config in your current directory and exits. No OmicsBox job is launched.
Step 2 — Customise it
Open the generated genetic_variation_analysis.config and edit it as described in Configuration: set your input paths and output folder, then fill in or comment/uncomment the step-specific flags you want to change. Save the file.
Step 3 — Run the workflow
nextflow run nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf \
-c genetic_variation_analysis.config \
-resumeNo clone required — the engine fetches the workflow for you.
Step 1 — Dump the configuration file
nextflow run BioBam/omicsbox-engine-workflows \
-r main \
-main-script nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf \
--dump_configThe template is written to your current directory exactly as in Option A.
Step 2 — Customise it
Edit the generated genetic_variation_analysis.config exactly as in Option A — see Configuration. Since the pipeline code lives remotely, this file is the only thing you own and edit.
Step 3 — Run the workflow
nextflow run BioBam/omicsbox-engine-workflows \
-r main \
-main-script nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf \
-c genetic_variation_analysis.config \
-resumeAll results are written under the output directory set in your configuration file (local_folder), inside a subfolder named after the Nextflow session ID of the run. Each step publishes to its own numbered directory, so every file can be traced back to the process that produced it:
results/
└── <session-id>/
├── 01_fastqc_raw/ # Quality-control report of the raw reads
├── 02_trimmomatic/ # Trimmed reads and the trimming report
│ └── unpaired/ # Reads that lost their mate during trimming, paired-end runs only
├── 03_fastqc_post/ # Quality-control report of the trimmed reads
├── 04_bwa/ # Genome alignments, the alignment report and its charts
├── 05_variant_calling/ # Raw variant call set, the calling report and its charts
├── 06_variant_filtering/ # Filtered variant call set, the filtering report and its charts
├── 07_beagle/ # Phased and imputed genotypes and the phasing report
├── 08_gwas/ # Association results and the GWAS report
└── 09_variant_annotation/ # Variant annotation table, its report and its chart
-
Nextflow
-
Snakemake