Skip to content

Nextflow Genetic Variation Analysis Workflow

rlopez edited this page Jul 28, 2026 · 2 revisions

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.


Workflow Architecture

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;
Loading

Pipeline Steps

  • 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 by FASTQC_POST and BWA, 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 fastqc on the trimmed reads so the effect of trimming can be compared against FASTQC_RAW. Like the raw-read assessment, it is a standalone diagnostic.
  • 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 by BCFTOOLS, 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 by VARIANT_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 both BEAGLE and VARIANT_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 by GWAS, 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 off VARIANT_FILTERING rather than continuing from BEAGLE by 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.

Inputs

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.


Configuration

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:

  1. Generate your own copy of the configuration file — Step 1 of Execution below.
  2. Open it in any text editor and read the inline comments; each option lists its accepted values and its default.
  3. Fill in the values you need and comment / uncomment the flags you want to enable or disable.
  4. 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.


Execution

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.

Option A — Local 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_config

This 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 \
    -resume

Option B — Directly from GitHub

No clone required — the engine fetches the workflow for you.

Step 1 — Dump the configuration file

nextflow run BioBam/omicsbox-engine-workflows \
    -r develop \
    -main-script nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf \
    --dump_config

The 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 develop \
    -main-script nextflow/workflows/genetic_variation_analysis/genetic_variation_analysis.nf \
    -c genetic_variation_analysis.config \
    -resume

Outputs

All 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

Clone this wiki locally