SNVPhyl

What does it do?

Use SNVPhyl to evaluate single-nucleotide variants between one reference genome and a set of closely related query isolates.

The automator retrieves a reference assembly and paired-end FASTQ files for the query isolates, checks whether the queries are sufficiently similar to the reference, and runs the SNVPhyl Nextflow pipeline with Singularity.

The output includes pairwise SNV counts, a phylogenetic tree, SNV tables, core-genome statistics, alignments, sample metadata, and pipeline-execution information.

SNVPhyl currently requires paired-end query reads containing both R1 and R2 files. Use Snippy when an analysis must combine paired-end and single-end raw-read inputs.

How do I use it?

Subject

In the Subject field, enter:

SNVPhyl

Spelling matters, but matching is not case-sensitive.

Description

Identify exactly one reference and at least one query isolate using this structure:

reference
REFERENCE-SEQID
compare
QUERY-SEQID-1
QUERY-SEQID-2

Rules:

  • the line after reference must contain exactly one reference SEQID or attached;
  • every line after compare is treated as a query SEQID;
  • blank lines are ignored;
  • each query must have paired-end FASTQ files containing both R1 and R2 reads.

Choose a high-quality assembly that is closely related to all query isolates as the reference.

Use a reference SEQID

reference
2026-SEQ-0001
compare
2026-SEQ-0002
2026-SEQ-0003
2026-SEQ-0004

Use an attached reference

Put attached after reference and attach one FASTA-formatted reference file:

reference
attached
compare
2026-SEQ-0002
2026-SEQ-0003
2026-SEQ-0004

If attached is specified without an attachment, the request stops with an error.

Optional parameters

The supplied documentation does not identify optional SNVPhyl analysis parameters beyond selecting a reference by SEQID or attachment.

Input validation and warnings

Before starting the pipeline, the automator checks that:

  • exactly one reference is specified;
  • a reference SEQID resolves to a FASTA assembly;
  • an attachment is present when attached is used;
  • query SEQIDs resolve to FASTQ data;
  • each included query has both R1 and R2 reads.

Missing query data are reported in the Redmine issue. Queries that appear divergent from the reference generate a warning, but the automator continues with available inputs.

Interpreting results

When SNVPhyl finishes, it uploads:

SNVPhyl_<issue-number>.zip

The archive is flattened: output files appear at the top level rather than in their original pipeline directories. If multiple files have the same name, a numeric suffix is added to preserve unique archive filenames.

Important outputs include:

snvMatrix.tsv

Contains pairwise SNV counts between analyzed samples. Use this file to review the number of SNVs separating each sample pair.

SNV counts should be interpreted together with core-genome coverage, reference suitability, and epidemiological context. A universal relatedness threshold is not defined by this documentation.

phylogeneticTree.newick

Contains the inferred phylogenetic tree in Newick format. Open it in a Newick-compatible viewer such as FigTree.

snvTable.tsv

Contains the table of SNVs identified by the workflow.

vcf2core.tsv

Contains core-genome and valid-position statistics. Use it to evaluate how much of the reference genome was included in the analysis.

Low core-genome coverage can indicate that one or more queries are too divergent from the reference for a reliable comparison.

snvAlignment.phy

Contains the SNV alignment in PHYLIP format.

metadata.tsv

Contains sample metadata generated by the pipeline.

Pipeline-information files

The archive can contain Nextflow execution reports, software information, and other pipeline metadata. Additional output types may include .tsv, .json, .txt, .newick, .bed, .html, .yml, .yaml, and .phy files.

How long does it take?

Runtime depends on the number of query isolates, read size and coverage, similarity to the reference, and available compute resources. Larger requests generally take longer than small requests.

What can go wrong?

No reference or multiple references are supplied

Symptom: The automator rejects the request before pipeline execution.

Likely cause: The Description does not identify exactly one reference.

What to do: Submit a new issue using the documented reference and compare structure.

The reference cannot be found

Symptom: The issue reports that the reference SEQID does not resolve to a FASTA file.

Likely cause: The SEQID is incorrect or its assembly is unavailable.

What to do: Verify the reference identifier or attach one valid FASTA reference.

attached is specified without an attachment

Symptom: The request stops with an attachment error.

Likely cause: No reference FASTA file was attached.

What to do: Attach one FASTA-formatted reference and submit a new issue.

Query FASTQ data are missing or incomplete

Symptom: The issue warns about missing queries, or a sample is omitted from the pipeline sample sheet.

Likely cause: The query cannot be found or does not have both R1 and R2 files.

What to do: Verify the query SEQID and ensure both paired-end files are available.

A query is too divergent from the reference

Symptom: The issue reports a divergence warning or vcf2core.tsv shows low core-genome coverage.

Likely cause: The reference is not sufficiently close to one or more queries.

What to do: Remove divergent queries or choose a more representative reference and submit a new analysis.

The Nextflow or Singularity pipeline fails

Symptom: The issue closes with an error note and may contain only partial output.

Likely cause: The pipeline or execution environment failed after processing began.

What to do: Review uploaded pipeline-information files and escalate persistent failures to the bioinformatics team.

No matching results are produced

Symptom: The archive contains NO_RESULTS.txt.

Likely cause: No expected result or pipeline-information files were found.

What to do: Review the issue errors and input validation, then correct the request or escalate the failure.

Software versions

When the issue closes, the automator reports the versions of:

  • Nextflow;
  • Singularity;
  • the SNVPhyl Nextflow pipeline.

Record these values when reproducibility is important.

  • Snippy — performs rapid haploid variant calling and can combine paired-end and single-end raw-read inputs.
  • COWSNPhR — maps raw query reads to a reference, calls variants with DeepVariant, annotates variant locations, and builds a tree.