SigProfilerExtractor

SigProfilerExtractor allows de novo extraction of mutational signatures from data generated in a matrix format. The tool identifies the number of operative mutational signatures, their activities in each sample, and the probability for each signature to cause a specific mutation type in a cancer sample. The tool makes use of SigProfilerMatrixGenerator and SigProfilerPlotting. Detailed documentation can be found at: https://osf.io/t6j7u/wiki/home/

The branch of SigProfilerExtractor has been modified for use with the SigProfiler Nextflow pipeline (SigProfiler.nf) in the Genomics England Research Environment.

Table of contents

• Installation
• Functions
  • importdata
  • sigProfilerExtractor
  • estimate_solution
  • decompose
  • PlotActivity.py
• Video Tutorials
• Copyright
• Contact Information

Installation

In the command line, please run the following:

$ pip install SigProfilerExtractor

Install your desired reference genome from the command line/terminal as follows (available reference genomes are: GRCh37, GRCh38, mm9, and mm10):

$ python
from SigProfilerMatrixGenerator import install as genInstall
genInstall.install('GRCh37')

This will install the human 37 assembly as a reference genome. You may install as many genomes as you wish.

Next, open a python interpreter and import the SigProfilerExtractor module. Please see the examples of the functions.

Functions

The list of available functions are:

• importdata
• sigProfilerExtractor
• estimate_solution
• decompose

And an additional script:

• plotActivity.py

importdata

Imports the path of example data.

importdata(datatype="matrix")

importdata Example

from SigProfilerExtractor import sigpro as sig
path_to_example_table = sig.importdata("matrix")
data = path_to_example_table
# This "data" variable can be used as a parameter of the "project" argument of the sigProfilerExtractor function.

# To get help on the parameters and outputs of the "importdata" function, please use the following:
help(sig.importdata)

sigProfilerExtractor

Extracts mutational signatures from an array of samples.

This version of SigProfilerExtractor has been modified for use with the SigProfilerExtract Nextflow pipeline (SigProfiler.nf) within the Genomics England Research Environment. It has been changed so that a separate job is run for each number of signatures and each NMF replicate. For each number of signatures, a job is then submitted to combine all NMF replicates. If between 1 and 20 signatures are being extracted, each with 100 replicates, then 2020 jobs will need to be submitted (20*100=2000 for each NMF replicate and each signature number, and 20 for combining the replicates for each signature number).

# Parameters to use
n_signatures=2 # Number of signatures to extract
nmf_replicates=10 # Number of NMF replicates to complete

# Run NMF replicates
for nmf_replicate in range(nmf_replicates):
    sigProfilerExtractor(input_type, out_put, input_data, section="nmf", minimum_signatures=n_signatures, maximum_signatures=n_signatures, nmf_replicates=nmf_replicates, nmf_replicate=nmf_replicate)

# Combine NMF replicates
sigProfilerExtractor(input_type, out_put, input_data, section="combine", minimum_signatures=n_signatures, maximum_signatures=n_signatures, nmf_replicates=nmf_replicates)

Category	Parameter	Variable Type	Parameter Description
Input Data
	input_type	String	The type of input: "vcf": used for vcf format inputs. "matrix": used for table format inputs using a tab seperated file.
	out_put	String	The name of the output folder. The output folder will be generated in the current working directory.
	input_data	String	Name of the input folder (in case of "vcf" type input) or the input file (in case of "table" type input). The project file or folder should be inside the current working directory. For the "vcf" type input, the project has to be a folder which will contain the vcf files in vcf format or text formats. The "text" type projects have to be a file.
	reference_genome	String	The name of the reference genome. The default reference genome is "GRCh37". This parameter is applicable only if the input_type is "vcf".
	opportunity_genome	String	The build or version of the reference signatures for the reference genome. The default opportunity genome is GRCh37. If the input_type is "vcf", the genome_build automatically matches the input reference genome value.
	context_type	String	A string of mutaion context name/names separated by comma (","). The items in the list defines the mutational contexts to be considered to extract the signatures. The default value is "96,DINUC,ID", where "96" is the SBS96 context, "DINUC" is the DINUCLEOTIDE context and ID is INDEL context.
	exome	Boolean	Defines if the exomes will be extracted. The default value is "False".
NMF Replicates
	section	String	Whether to run the NMF or NMF-combination section of SigProfilerExtractor. Options are "nmf" and "combine".
	minimum_signatures	Positive Integer	The minimum number of signatures to be extracted. The default value is 1.
	maximum_signatures	Positive Integer	The maximum number of signatures to be extracted. The default value is 25.
	nmf_replicates	Positive Integer	The number of iteration to be performed to extract each number signature. The default value is 500.
	nmf_replicate	Positive Integer	The NMF replicate to complete. Should be a value between 1 and the total number of replicates to perform, inclusive. Ignored if replicates are being combined (i.e. section equals "combine")
	resample	Boolean	Default is True. If True, add poisson noise to samples by resampling.
	seeds	String	It can be used to get reproducible resamples for the NMF replicates. A path of a tab separated .txt file containing the replicated id and preset seeds in a two columns dataframe can be passed through this parameter. The Seeds.txt file in the results folder from a previous analysis can be used for the seeds parameter in a new analysis. The Default value for this parameter is "none". When "none", the seeds for resampling will be random for different analysis.
NMF Engines
	nmf_init	String	The initialization algorithm for W and H matrix of NMF. Options are "random", "nndsvd", "nndsvda", "nndsvdar" and "nndsvd_min"'". Default is "random".
	precision	String	Values should be single or double. Default is single.
	matrix_normalization	String	Method of normalizing the genome matrix before it is analyzed by NMF. Other options are, "log2", "custom" or "none". Default is value is "gmm".
	beta	Integer	Value defines whether (0) Itakura-Saito updates, (1) generalised Kullback-Leibler updates, or (2) Euclidean updates are used. Default is 2 (Euclidean updates).
	min_nmf_iterations	Integer	Value defines the minimum number of iterations to be completed before NMF converges. Default is 10000.
	max_nmf_iterations	Integer	Value defines the maximum number of iterations to be completed before NMF converges. Default is 1000000.
	nmf_test_conv	Integer	Value defines the number number of iterations to done between checking next convergence. Default is 10000.
	nmf_tolerance	Float	Value defines the tolerance to achieve to converge. Default is 1e-15.
Execution
	cpu	Integer	The number of processors to be used to extract the signatures. The default value is -1 which will use all available processors.
	gpu	Boolean	Defines if the GPU resource will used if available. Default is False. If True, the GPU resources will be used in the computation.
	batch_size	Integer	Will be effective only if the GPU is used. Defines the number of NMF replicates to be performed by each CPU during the parallel processing. Default is 1.
Solution Estimation Thresholds
	stability	Float	Default is 0.8. The cutoff thresh-hold of the average stability. Solutions with average stabilities below this thresh-hold will not be considered.
	min_stability	Float	Default is 0.2. The cutoff thresh-hold of the minimum stability. Solutions with minimum stabilities below this thresh-hold will not be considered.
	combined_stability	Float	Default is 1.0. The cutoff thresh-hold of the combined stability (sum of average and minimum stability). Solutions with combined stabilities below this thresh-hold will not be considered.
Decomposition
	cosmic_version	Float	Takes a positive float among 1, 2, 3, 3.1, 3.2. Default is 3.1. Defines the version of COSMIC reference signatures.
	de_novo_fit_penalty	Float	Takes any positive float. Default is 0.02. Defines the weak (remove) thresh-hold cutoff to assign denovo signatures to a sample.
	nnls_add_penalty	Float	Takes any positive float. Default is 0.05. Defines the strong (add) thresh-hold cutoff to assign COSMIC signatures to a sample.
	nnls_remove_penalty	Float	Takes any positive float. Default is 0.01. Defines the weak (remove) thresh-hold cutoff to assign COSMIC signatures to a sample.
	initial_remove_penalty	Float	Takes any positive float. Default is 0.05. Defines the initial weak (remove) thresh-hold cutoff to COSMIC assign signatures to a sample.
	refit_denovo_signatures	Boolean	Default is True. If True, then refit the denovo signatures with nnls.
	make_decomposition_plots	Boolean	Defualt is True. If True, Denovo to Cosmic sigantures decompostion plots will be created as a part the results.
	collapse_to_SBS96	Boolean	Defualt is True. If True, SBS288 and SBS1536 Denovo signatures will be mapped to SBS96 reference signatures. If False, those will be mapped to reference signatures of the same context.
Others
	get_all_signature_matrices	Boolean	If True, the Ws and Hs from all the NMF iterations are generated in the output.
	export_probabilities	Boolean	Defualt is True. If False, then doesn't create the probability matrix.

sigProfilerExtractor Output

To learn about the output, please visit https://osf.io/t6j7u/wiki/home/

Estimation of the Optimum Solution

Estimate the optimum solution (rank) among different number of solutions (ranks).

ebs.estimate_solution(base_csvfile="All_solutions_stat.csv",
          All_solution="All_Solutions",
          genomes="Samples.txt",
          output="results",
          title="Selection_Plot",
          stability=0.8,
          min_stability=0.2,
          combined_stability=1.25)

Parameter	Variable Type	Parameter Description
base_csvfile	String	Default is "All_solutions_stat.csv". Path to a csv file that contains the statistics of all solutions.
All_solution	String	Default is "All_Solutions". Path to a folder that contains the results of all solutions.
genomes	String	Default is Samples.txt. Path to a tab delimilted file that contains the mutation counts for all genomes given to different mutation types.
output	String	Default is "results". Path to the output folder.
title	String	Default is "Selection_Plot". This sets the title of the selection_plot.pdf
stability	Float	Default is 0.8. The cutoff thresh-hold of the average stability. Solutions with average stabilities below this thresh-hold will not be considered.
min_stability	Float	Default is 0.2. The cutoff thresh-hold of the minimum stability. Solutions with minimum stabilities below this thresh-hold will not be considered.
combined_stability	Float	Default is 1.0. The cutoff thresh-hold of the combined stability (sum of average and minimum stability). Solutions with combined stabilities below this thresh-hold will not be considered.

Estimation of the Optimum Solution Example

from SigProfilerExtractor import estimate_best_solution as ebs
ebs.estimate_solution(base_csvfile="All_solutions_stat.csv",
          All_solution="All_Solutions",
          genomes="Samples.txt",
          output="results",
          title="Selection_Plot",
          stability=0.8,
          min_stability=0.2,
          combined_stability=1.25)

Estimation of the Optimum Solution Output

The files below will be generated in the output folder:

File Name	Description
All_solutions_stat.csv	A csv file that contains the statistics of all solutions.
selection_plot.pdf	A plot that depict the Stability and Mean Sample Cosine Distance for different solutions.

Decompose

Decomposes the De Novo Signatures into COSMIC Signatures and assigns COSMIC signatures into samples

decompose(signatures, activities, samples,  output, signature_database=None, nnls_add_penalty=0.05, nnls_remove_penalty=0.01, initial_remove_penalty=0.05, de_novo_fit_penalty=0.02, genome_build="GRCh37", refit_denovo_signatures=True, make_decomposition_plots=True, connected_sigs=True, verbose=False)

Parameter	Variable Type	Parameter Description
signatures	String	Path to a tab delimited file that contains the signaure table where the rows are mutation types and colunms are signature IDs.
activities	String	Path to a tab delimilted file that contains the activity table where the rows are sample IDs and colunms are signature IDs.
samples	String	Path to a tab delimilted file that contains the activity table where the rows are mutation types and colunms are sample IDs.
output	String	Path to the output folder.
de_novo_fit_penalty	Float	Takes any positive float. Default is 0.02. Defines the weak (remove) thresh-hold cutoff to be assigned denovo signatures to a sample. Optional parameter.
nnls_add_penalty	Float	Takes any positive float. Default is 0.01. Defines the weak (remove) thresh-hold cutoff to be assigned COSMIC signatures to a sample. Optional parameter.
nnls_remove_penalty	Float	Takes any positive float. Default is 0.01. Defines the weak (remove) thresh-hold cutoff to be assigned COSMIC signatures to a sample. Optional parameter.
initial_remove_penalty	Float	Takes any positive float. Default is 0.05. Defines the initial weak (remove) thresh-hold cutoff to be COSMIC assigned signatures to a sample. Optional parameter.
genome_build	String	The genome type. Example: "GRCh37", "GRCh38", "mm9", "mm10". The default value is "GRCh37"
verbose	Boolean	Prints statements. Default value is False.

Decompose Example

from SigProfilerExtractor import decomposition as decomp
signatures = "path/to/De_Novo_Solution_Signatures.txt"
activities="path/to/De_Novo_Solution_Activities.txt"
samples="path/to/Samples.txt"
output="name or path/to/output"
decomp.decompose(signatures, activities, samples, output, genome_build="GRCh37", verbose=False)

Decompose Output

Values: The files below will be generated in the output folder:

• Cluster_of_Samples.txt
• comparison_with_global_ID_signatures.csv
• Decomposed_Solution_Activities.txt
• Decomposed_Solution_Samples_stats.txt
• Decomposed_Solution_Signatures.txt
• decomposition_logfile.txt
• dendogram.pdf
• Mutation_Probabilities.txt
• Signature_assaignment_logfile.txt
• Signature_plot[MutatutionContext]_plots_Decomposed_Solution.pdf

Activity Stacked Bar Plot

Generates a stacked bar plot showing activities in individuals

plotActivity(activity_file, output_file = "Activity_in_samples.pdf", bin_size = 50, log = False)

Parameter	Variable Type	Parameter Description
activity_file	String	The standard output activity file showing the number of, or percentage of mutations attributed to each sample. The row names should be samples while the column names should be signatures.
output_file	String	The path and full name of the output pdf file, including ".pdf"
bin_size	Integer	Number of samples plotted per page, recommended: 50

Activity Stacked Bar Plot Example

$ python plotActivity.py 50 sig_attribution_sample.txt test_out.pdf

Video Tutorials

Take a look at our video tutorials for step-by-step instructions on how to install and run SigProfilerExtractor on Amazon Web Services.

Tutorial #1: Installing SigProfilerExtractor on Amazon Web Services

Tutorial #2: Running the Quick Start Example Program

Tutorial #3: Reviewing the output from SigProfilerExtractor

GPU support

If CUDA out of memory exceptions occur, it will be necessary to reduce the number of CPU processes used (the cpu parameter).

For more information, help, and examples, please visit: https://osf.io/t6j7u/wiki/home/

Copyright

This software and its documentation are copyright 2018 as a part of the sigProfiler project. The SigProfilerExtractor framework is free software and is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.