SigProfilerMatrixGenerator

SigProfilerMatrixGenerator creates mutational matrices for all types of somatic mutations. It allows downsizing the generated mutations only to parts of the genome (e.g., exome or a custom BED file). The tool seamlessly integrates with other SigProfiler tools.

INTRODUCTION

The purpose of this document is to provide a guide for using the SigProfilerMatrixGenerator framework to generate mutational matrices for a set of samples with associated mutational catalogues. Full documentation is available in docs/ (rendered via MkDocs): https://sigprofilersuite.github.io/SigProfilerMatrixGenerator/

For users that prefer working in an R environment, a wrapper package is provided and can be found and installed from: https://github.com/SigProfilerSuite/SigProfilerMatrixGeneratorR

DOCUMENTATION

• Source Markdown lives in docs/ and is rendered via MkDocs to https://sigprofilersuite.github.io/SigProfilerMatrixGenerator/
• Local preview:
  • python3 -m mkdocs serve
  • python3 -m mkdocs build && open site/index.html
• Optional (mirror OSF wiki + images): python3 tools/mirror_osf_wiki.py --node s93d5 (use OSF_TOKEN=... for private assets)
• Optional (offline images for existing docs): python3 tools/fetch_osf_assets.py

PREREQUISITES

The framework is written in PYTHON, however, it also requires the following software with the given versions (or newer):

• PYTHON version 3.8 or newer
• WGET version 1.9 or RSYNC if you have a firewall

By default the installation process will save the FASTA files for all chromosomes for the default genome assemblies (GRCh37, GRCH38, mm10, mm9, rn6). As a result, ~3 Gb of storage must be available for the downloads for each genome.

QUICK START GUIDE

Using Python Interface:

This section will guide you through the minimum steps required to create mutational matrices:

1. Install the python package using pip:

   pip install SigProfilerMatrixGenerator
   

2. Install your desired reference genome from the command line/terminal as follows (a complete list of supported genomes can be found below):

   $ python
   >> from SigProfilerMatrixGenerator import install as genInstall
   >> genInstall.install('GRCh37', rsync=False, bash=True)
   

    This will install the human 37 assembly as a reference genome. You may install as many genomes as you wish. If you have a firewall on your server, you may need to install rsync and use the rsync=True parameter. Similarly, if you do not have bash,
    use bash=False.
   

3. Place your vcf files in your desired output folder. It is recommended that you name this folder based on your project's name
4. From within a python session, you can now generate the matrices as follows:

   $ python3
   >>from SigProfilerMatrixGenerator.scripts import SigProfilerMatrixGeneratorFunc as matGen
   >>matrices = matGen.SigProfilerMatrixGeneratorFunc("test", "GRCh37", "/Users/ebergstr/Desktop/test",plot=True, exome=False, bed_file=None, chrom_based=False, tsb_stat=False, seqInfo=False, cushion=100)
   

The required parameters are as follows:

SigProfilerMatrixGeneratorFunc(project, reference_genome, path_to_input_files)

Using Command Line Interface (CLI):

1. After installing the package, you can directly call the tool using:

   SigProfilerMatrixGenerator <function-name> <arguments>
   

   Currently supported functions are 'install' and 'matrix_generator'.

2. For example, to install a reference genome:

   SigProfilerMatrixGenerator install GRCh37
   

3. To generate SBS, DBS, or INDEL matrices:

   SigProfilerMatrixGenerator matrix_generator <project> <reference_genome> <path_to_input_files>
   

View the table below for the full list of parameters.

PARAMETERS | Category | Parameter | Variable Type | Parameter Description | | ------ | ----------- | ----------- | ----------- | | Required | | | | | | project | String | The name of the project. | | | reference_genome | String | The name of the reference genome. Full list of genomes under Supported Genomes section. Supported values include the following: {c_elegans, dog, ebv, GRCh37, GRCh38, mm9, mm10, mm39, rn6, yeast} | | | path_to_input_files | String | The path to the input files. | | Optional | | | | | | exome | Boolean | Downsamples mutational matrices to the exome regions of the genome. Default value False. | | | bed_file | String | Downsamples mutational matrices to custom regions of the genome. Requires the full path to the BED file. Default value None. Note: BED file header is required. | | | chrom_based | Boolean | Outputs chromosome-based matrices. Default value False. | | | plot | Boolean | Integrates with SigProfilerPlotting to output all available visualizations for each matrix. Default value False. | | | tsb_stat | Boolean | Outputs the results of a transcriptional strand bias test for the respective matrices. Default value False. | | | seqInfo | Boolean | Ouputs original mutations into a text file that contains the SigProfilerMatrixGenerator classificaiton for each mutation. Default value True. | | | cushion | Integer | Adds an Xbp cushion to the exome/bed_file ranges for downsampling the mutations. Default value 100. | | | volume | String | Path to SigProfilerMatrixGenerator's volume where reference genomes will be saved and loaded from (for Docker/Singularity conatiners). The environmental variable 'SIGPROFILERMATRIXGENERATOR_VOLUME' takes precedence. Default value is None. |

INPUT FILE FORMAT

This tool currently supports maf, vcf, and simple text file. The user must provide variant data adhering to one of these three formats. If the user’s files are in vcf format, each sample must be saved as a separate files.

OUTPUT FILE STRUCTURE

The output structure is divided into three folders: input, output, and logs. The input folder contains copies of the user-provided input files. The outputfolder contains a DBS, SBS, ID, and TSB folder (there will also be a plots folder if this parameter is chosen). The matrices are saved into the appropriate folders. The logs folder contains the error and log files for the submitted job.

STRUCTURAL VARIANT MATRIX GENERATION

INPUT FORMAT:

First six columns are required, and either the column "svclass" (deletion, translocation, tandem-duplication, or inversion) or the columns "strand1" & "strand2" (BRASS convention, see https://github.com/cancerit/BRASS/wiki/BEDPE) must also be present

Example with SV class present (tsv or csv file):

| sample | chrom1 | start1 | end1 | chrom2 | start2 | end2 | svclass | |:-------:|:------:|:--------:|:--------:|:------:|:--------:|:--------:|:--------:| | Sample1 | 19 | 21268384 | 21268385 | 19 | 21327858 | 21327859 | deletion |

Example without SV class present (tsv or csv file):

| sample | chrom1 | start1 | end1 | chrom2 | start2 | end2 | strand1 | strand2 | |:-------:|:------:|:--------:|:--------:|:------:|:--------:|:--------:|:-------:|:-------:| | Sample1 | 19 | 21268384 | 21268385 | 19 | 21327858 | 21327859 | + | + |

Quick Start Example:

from SigProfilerMatrixGenerator.scripts import SVMatrixGenerator as sv
input_dir = "./SigProfilerMatrixGenerator/references/SV/example_input/560-Breast" #directory which contains collection of bedpe files (one per sample)
output_dir = "./SigProfilerMatrixGenerator/references/SV/example_output/"
project = "560-Breast"
sv.generateSVMatrix(input_dir, project, output_dir)

Alternatively, you can run directly from the command line:

SigProfilerMatrixGenerator sv_matrix_generator $input_dir $project $output_dir

OUTPUT:

1. Annotated bedpe file - a file with each SV annotated with its type, size bin, and clustered/non-clustered status
2. Aggregate SV plot - a summary plot showing the average number of events in each channel for the whole cohort of samples
3. SV Matrix - a 32 X n matrix (where n is the number of samples) that can be used to perform signature decomposition, clustering, etc.

VCF INPUT FORMAT:

Note that VCF format (4.1, 4.2 and 4.3) is now supported. If using VCFs, please make sure the files in your input directory end with .vcf. Manta, Delly, Lumpy and GRIDSS are supported and example test files can be found in the references/SV/ folder

Quick Start Example:

#navigate to SVMatrixGenerator directory and start python3 interpreter

from SigProfilerMatrixGenerator.scripts import SVMatrixGenerator as sv
input_dir = "./SigProfilerMatrixGenerator/references/SV/example_input/VCF/" #directory which contains collection of VCF files (one per sample)
output_dir = "./SigProfilerMatrixGenerator/references/SV/example_output/"
project = "vcf-test" #test manta, delly, lumpy, and gridss vcf files
sv.generateSVMatrix(input_dir, project, output_dir)

Alternatively, you can run directly from the command line:

input_dir="./SigProfilerMatrixGenerator/references/SV/example_input/VCF/"
project="vcf-test"
output_dir="results"
SigProfilerMatrixGenerator sv_matrix_generator $