Usage

Running python helmsman.py -h will display a help message with detailed information for each option.

usage: helmsman.py [-h] [-c [INT]] [-S [INT]] [-v] [-V] [-M [STR]] -i
                   [/path/to/input.vcf] [-w] [-f [/path/to/genome.fa]]
                   [-s [/path/to/kept_samples.txt]] [-g [STR]] [-C [INT]]
                   [-X [INT]] [-p [/path/to/project_directory]] [-m [STR]]
                   [-k [STR]] [-d [STR]] [-r [INT]] [-l [INT]]

optional arguments:
  -h, --help            show this help message and exit
  -c [INT], --cpus [INT]
                        number of CPUs. Must be integer value between 1 and 10
  -S [INT], --seed [INT]
                        random seed for NMF and outlier detection
  -v, --verbose         Enable verbose logging
  -V, --version         show program's version number and exit
  -M [STR], --mode [STR]
                        Mode for parsing input. Must be one of {vcf, maf, agg,
                        txt}. Defaults to VCF mode.
  -i [/path/to/input.vcf], --input [/path/to/input.vcf]
                        In VCF mode (default) input file is a VCF or text file
                        containing paths of multiple VCFs. Defaults to accept
                        input from STDIN with "--input -". In aggregation
                        mode, input file is a text file containing mutation
                        subtype count matrices, or paths of multiple such
                        matrices. In plain text mode, input file is tab-
                        delimited text file containing 5 columns: CHR, POS,
                        REF, ALT, ID
  -w, --rowwise         Compile mutation spectra matrix from VCF files
                        containing non-overlapping samples.
  -f [/path/to/genome.fa], --fastafile [/path/to/genome.fa]
                        reference fasta file
  -s [/path/to/kept_samples.txt], --samplefile [/path/to/kept_samples.txt]
                        file with sample IDs to include (one per line)
  -g [STR], --groupvar [STR]
                        if --samplefile is provided with VCF input, or if
                        input is MAF file, specify column name of the grouping
                        variable to pool samples by. If left blank, matrix
                        will be constructed per sample/tumor ID as usual
  -u, --impute          if using VCF input mode, missing genotypes (i.e.,
                        "./.") will be imputed as the allele frequency of the
                        samples with non-missing genotypes
  -C [INT], --minsnvs [INT]
                        minimum # of SNVs per individual to be included in
                        analysis. Default is 0.
  -X [INT], --maxac [INT]
                        maximum allele count for SNVs to keep in analysis.
                        Defaults to 0 (all variants)
  -p [/path/to/project_directory], --projectdir [/path/to/project_directory]
                        directory to store output files (do NOT include a
                        trailing '/'). Defaults to ./helmsman_output
  -m [STR], --matrixname [STR]
                        filename prefix for M matrix [without extension]
  -k [STR], --package [STR]
                        To use the mutation spectra matrix generated by
                        Helmsman with a specific mutation signature analysis
                        package, this option will print out the code necessary
                        to load the Helmsman output into R and reformat for
                        compatibility with one of the following packages:
                        {SomaticSignatures, deconstructSigs, signeR}.
  -d [STR], --decomp [STR]
                        mode for matrix decomposition. Must be one of {nmf,
                        pca}. Defaults to pca.
  -r [INT], --rank [INT]
                        Rank for Matrix decomposition. If --decomp pca, will
                        select first r components. Default [0] will force
                        Helmsman to iterate through multiple ranks to find an
                        optimal choice.
  -l [INT], --length [INT]
                        motif length. Allowed values are 1,3,5,7

Program options

--cpus [INT]

Set the number of CPUs to use if input is a list of files.

--seed [INT]

Set the random seed to be used for NMF decomposition and outlier detection algorithms. If not specified, a random seed will be assigned and printed to the output if you need to reproduce results of a particular run.

--verbose

This flag enables debug logging for troubleshooting.

--version

Show program's version number and exit.

Input options

These options specify the data to be processed by Helmsman. By default, Helmsman assumes input is a VCF file or text file containing file paths of multiple VCF files.

Reference genome

--fastafile [/path/to/genome.fa]

In VCF mode, MAF mode, and plain text mode, you must specify the fasta-formatted reference genome to be used to look up the local sequence context for each SNV. This file must corresponding to the same reference genome build used to call the variants contained in the input file. The fasta file may be either uncompressed or bgzip-compressed.

VCF mode

--mode vcf

Helmsman can accept variant call format (VCF) or binary call format (BCF) files, either uncompressed or bgzip-compressed. VCF/BCF files are assumed to be formatted with mandatory columns (#CHROM, POS, ID, REF, ALT, QUAL, FILTER, INFO). This VCF must contain an allele count field in the INFO column ([AC=N]), and include individual genotypes (i.e., the VCF cannot be a "sites-only" file).

Single VCF file

--mode vcf --input /path/to/input.vcf

The VCF input can be either a file on disk or piped from STDIN (using --input -), enabling compatibility with a wide range of existing pipelines and workflows. The VCF can contain any combination of variant types (e.g., SNVs, indels, CNVs), allele counts, or filter flags. By default, Helmsman will only analyze singleton SNVs with a "PASS" value in the FILTER column of the VCF.

Multiple VCF files, same samples

--mode vcf --input /path/to/vcfs.txt

If your data are spread across multiple files, each containing the same samples (e.g., one VCF per chromosome), Helmsman will accept a plain text file containing the absolute file paths (one per line) for the VCF files to process. This assumes all VCF files contain the exact same sample IDs and that the IDs in the VCF header are ordered identically across all subfiles. This option is best used in conjunction with the --cpus {N} argument to enable parallel processing of the files.

Multiple VCF files, different samples

--mode vcf --input /path/to/vcfs.txt --rowwise

If you instead have VCFs containing non-overlapping subsets of the sample (e.g., one per individual), use the --rowwise flag to properly generate the mutation spectra matrix.

Restrict to specific samples

--samplefile /path/to/samples.txt

If your input VCF file(s) contains samples that you do not wish to analyze, provide a tab-delimited text file containing the sample IDs you wish to keep. This file can contain any number of columns, as long as the sample IDs are contained in the first column, and the file has a header with column names (the first column must be named ID).

Pool samples together

--samplefile /path/to/samples.txt --groupvar GROUP

In some cases it may be necessary (or desired) to run Helmsman with samples pooled together in some way. For example, if samples were sequenced on different dates and we want to explicitly look for batch effects, we can supply a file containing sample IDs in the ID column and the sequencing date in the DATE. If the --groupvar DATE option is used, Helmsman will pool samples by the value present in the DATE column rather than the ID column.

Note that the --samplefile option will operate as above--only samples present in this file will be considered when generating the mutation spectra matrix.

Impute missing genotypes

--impute

By default, when using VCF mode, samples with missing genotypes (i.e., "./.") are coded as a 0, and the mutation spectra matrix does not get incremented for those samples. The --impute option forces any missing genotypes to be set to the average allele frequency of the non-missing samples. For example, for a given site, if there are 11 samples in the VCF file with one sample missing a genotype, 5 samples homozygous for the reference allele and 5 heterozygous, this option will impute the genotype for the missing sample as 0.5. Users should exercise caution when using this option, as assumptions about the allele frequency across samples may not be valid for VCF files containing heterogeneous tumor samples.

MAF mode

--mode maf --input /path/to/input.maf

Helmsman can also accept Mutation Annotation Format files. By default, SNVs will be counted per unique identifier in the Tumor_Sample_Barcode column, but any column can be specified using the --groupvar option.

TXT mode

--mode txt --input /path/to/input.txt

Helmsman can also accept a tab-delimited text file, containing a list of SNVs with the following 5 columns (order must be maintained):

Aggregation mode

This mode can be used to run Helmsman on one or more existing mutation spectra matrices, which can be obtained from the output of previous Helmsman runs.

Re-run on a single previously-generated matrix

--mode agg --input /path/to/subtype_count_matrix.txt

Suppose you have already run Helmsman on a large dataset and generated the mutation spectra matrix, but wish to re-run it with different outlier detection parameters. Rather than re-running on the original data, you can use aggregation mode with the existing mutation spectra matrix as the input file.

Combine multiple matrices with different samples

--mode agg --input /path/to/m_samples.txt

If you have generated mutation spectra matrices from different non-overlapping subsamples (e.g., one VCF per individual), you can use aggregation mode to run a combined analysis on all samples together. Simply put the absolute file paths for each of the matrices (one per line) into a text file named /path/to/m_samples.txt

For example, if you have run Helmsman on one sample of N individuals and another of M individuals, this will create an (N+M)x96 matrix and run the combined analysis.

We advise users to exercise caution with interpreting results of aggregated samples, as different datasets can have different SNV distributions.

Combine multiple matrices from different genomic regions

--mode agg --input /path/to/m_regions.txt

Similarly, if you have generated mutation spectra matrices from different non-overlapping genomic regions (e.g., one per chromsome), but in the same sample, put the absolute file paths for each of the matrices (one per line) into a text file named /path/to/m_regions.txt, and Helmsman will sum the elements of each matrix. When combining by region, it is essential that the matrices have the exact same number of samples.

If you anticipate generating multiple mutation spectra matrices by sample or by region to be aggregated at a later point, we recommend setting a unique name for the output file using the --matrixname custom_output_name option and/or putting the results of each run in a different directory with the --projectdir option, to avoid mixing up which output files are being generated.

Filtering options

Helmsman is designed to integrate in existing VCF processing workflows, so if you wish to apply sample-level or variant-level filters to your input data prior to running Helmsman, we advise pre-filtering your data (e.g., using bcftools) for greater flexibility and efficiency. However, we have included options that enable the user to perform a few common filtering tasks directly in Helmsman.

Exclude samples with too few SNVs

--minsnvs [INT]

In some cases, samples may appear as outliers simply because they have very few observed SNVs. The --minsnvs parameter forces Helmsman to only evaluate individuals with at least X observed SNVs. By default, minsnvs=0, and all samples are retained. If this option is enabled, the low-SNV outliers will be written to a separate file named helmsman_snvs_lt{X}.txt in the output directory, and the keep/drop lists will be derived from the remaining subset of samples.

Note that the chisq outlier detection mode is generally more robust to low-SNV outliers.

Specify maximum allele count of SNVs to analyze

--maxac [INT]

By default, Helmsman will evaluate all SNVs present in the input data [--maxac 0]. To include more common SNVs, up to a specific allele count threshold, increase the value of this parameter. For example, --maxac 2 will include only singletons and doubletons.

Output options

Output directory

--projectdir [/path/to/project_directory]

By default, output files are stored in a subfolder named /helmsman_output/ in your current directory. The --projectdir parameter will specify a custom name/location for the Helmsman output directory.

Customize matrix prefix

--matrixname [STR]

This parameter allows you to specify a custom name for the mutation spectra matrix file. The default is --matrixname subtype_count_matrix. This is particularly useful if you wish to generate an initial count matrix then play around with the outlier detection parameters.

Matrix decomposition options

NMF decomposition

--decomp nmf

Helmsman will decompose the subtype count matrix using Nonnegative Matrix Factorization (NMF), as implemented in the nimfa Python library.

PCA decomposition

--decomp pca

Helmsman will decompose the subtype count matrix using Principal Component Analysis (PCA).

Motif length

--length {1,3,5,7}

This parameter specifies the (symmetric) motif length to be considered in determining the mutation subtypes. The default (3) produces 96 3-mer subtypes, which is likely sufficient for QC of whole-genome germline variants. If you are using Helmsman for QC of whole-exome germline variants, you will likely need to specify --length 1, as most individuals will not have enough singleton variants to accurately infer higher-order mutation signatures. Values greater than 3 will likely lead to extremely noisy or unreliable QC results for germline variants, but may be useful for examining somatic sequencing data.

Decomposition rank

--rank [INT]

Set the rank of the NMF decomposition to R components if using --decomp nmf, or select the first R principal components if using --decomp pca.

Integration with other mutation signature analysis packages

--package [STR]

If you plan to use the output of Helmsman in other mutation signature analysis packages, this option will automatically generate a small R script with all the code necessary to read the mutation spectra matrix and format it for compatibility with the specified tool, using functions from the musigtools package. This script will be stored in the directory specified by --projectdir. When Helmsman finishes generating the mutation spectra matrix, it will provide a command to run this script, e.g., source("path/to/project_directory/Helmsman_to_SomaticSignatures.R")