Merge pull request #19 from AlexandrovLab/dev_v3

SPA v0.0.6

Author: rvangara

.DS_Store

@@ -1,8 +1,11 @@
 [![License](https://img.shields.io/badge/License-BSD\%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause)
 [![Build Status](https://api.travis-ci.com/AlexandrovLab/SigProfilerAssignment.svg)](https://app.travis-ci.com/AlexandrovLab/SigProfilerAssignment)
 
-# SigProfilerAssignment
 
+
+<img src="SigProfilerAssignment/src/figures/SigProfilerAssignment.png" alt="drawing" width="1000"/>
+
+# SigProfilerAssignment
 SigProfilerAssignment is a new mutational attribution and decomposition tool that performs the following functions:
 -   Attributing a known set of mutational signatures to an individual sample or multiple samples.
 -   Decomposing de novo signatures to COSMIC signature database.
@@ -25,9 +28,37 @@ Unzip the contents of SigProfilerExtractor-master.zip or the zip file of a corre
 $ cd SigProfilerAssignment-master
 $ pip install .
 ```
+## Signature Subtypes
+```python
+signature_subgroups = ['remove_MMR_deficiency_signatures',
+                       'remove_POL_deficiency_signatures',
+                       'remove_HR_deficiency_signatures' ,
+                       'remove_BER_deficiency_signatures',
+                        'remove_Chemotherapy_signatures', 
+                        'remove_APOBEC_signatures', 
+                        'remove_Tobacco_signatures', 
+                        'remove_UV_signatures', 
+                        'remove_AA_signatures',
+                        'remove_Colibactin_signatures', 
+                        'remove_Artifact_signatures', 
+                        'remove_Lymphoid_signatures']
+```
 
 
-Decomposes the De Novo Signatures into COSMIC Signatures and assigns COSMIC signatures into samples
+| Signature Subgroup      | SBS Signatures that are excluded |
+| ----------- | ----------- |
+|MMR_deficiency_signatures|	6, 14, 15, 20, 21, 26, 44|
+|POL_deficiency_signatures|	10a, 10b, 10c, 10d, 28|
+|HR_deficiency_signatures|	3|
+|BER_deficiency_signatures|	30, 36|
+|Chemotherapy_signatures|	11, 25, 31, 35, 86, 87, 90|
+|APOBEC_signatures|	2, 13|
+|Tobacco_signatures	|4, 29, 92|
+|UV_signatures|	7a, 7b, 7c, 7d, 38|
+|AA_signatures|	22|
+|Colibactin_signatures|	88|
+|Artifact_signatures|	27, 43, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60|
+|Lymphoid_signatures|	9, 84, 85|
 
 <!-- 
 ```python
@@ -36,29 +67,62 @@ spa_analyze(  samples,  output, signatures=None, signature_database=None,decompo
               genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False): 
 ```  -->
 ### Decompose Fit
+Decomposes the De Novo Signatures into COSMIC Signatures and assigns COSMIC signatures into samples.
+<img src="SigProfilerAssignment/src/figures/decomp_pic.jpg" alt="drawing" width="600"/>
+
 ```python
 from SigProfilerAssignment import Analyzer as Analyze
-Analyze.decompose_fit(samples,  output, signatures=None, signature_database=None,genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False)
+Analyze.decompose_fit(samples, 
+                       output, 
+                       signatures=signatures,
+                       signature_database=sigs,
+                       genome_build="GRCh37", 
+                       verbose=False,
+                       new_signature_thresh_hold=0.8,
+                       signature_subgroups=signature_subgroups)
 ```
 ### *De Novo* Fit
+Attributes mutations of given Samples to input denovo signatures.
+<img src="SigProfilerAssignment/src/figures/denovo_fit.jpg" alt="drawing" width="600"/>
+
 ```python
 from SigProfilerAssignment import Analyzer as Analyze
-Analyze.denovo_fit(samples,  output, signatures=None, signature_database=None,genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False)
+Analyze.denovo_fit( samples,
+                    output, 
+                    signatures=signatures,
+                    signature_database=sigs,
+                    genome_build="GRCh37", 
+                    verbose=False)
 ```
-### Cosmic Fit
+### COSMIC Fit
+Attributes mutations of given Samples to input COSMIC signatures. Note that penalties associated with denovo fit and COSMIC fits are different.
+<img src="SigProfilerAssignment/src/figures/cosmic_fit.jpg" alt="drawing" width="600"/>
+
 ```python
 from SigProfilerAssignment import Analyzer as Analyze
-Analyze.cosmic_fit(samples,  output, signatures=None, signature_database=None,genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False)
+Analyze.cosmic_fit( samples, 
+                    output, 
+                    signatures=None,
+                    signature_database=sigs,
+                    genome_build="GRCh37", 
+                    verbose=False,
+                    collapse_to_SBS96=False,
+                    signature_subgroups=signature_subgroups,
+                    make_plots=True)
 ```
-## Parameters
+## Main Parameters
 | 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. |
 | **genome_build** | String | The genome type. Example: "GRCh37", "GRCh38", "mm9", "mm10". The default value is "GRCh37" |
+| **new_signature_thresh_hold**|Float | Parameter in Cosine similarity to declare a  new signature. Applicable for decompose fit only. The default value is 0.8  |
+| **make_plots** | Boolean | Toggle on and off for making and saving all plots. Default value is True.  |
+| **signature_subgroups** | List | Removes the signatures corresponding to specific subtypes for better fitting. The usage is given above. Default value is None.  |
 | **verbose** | Boolean | Prints statements. Default value is False.  |
+
         
 
 #### SPA analysis Example
@@ -70,15 +134,23 @@ import SigProfilerAssignment as spa
 from SigProfilerAssignment import Analyzer as Analyze
 
 #set directories and paths to signatures and samples
-dir_inp = spa.__path__[0]+'/data/Examples/'
-signatures = dir_inp+"Results_scenario_8/SBS96/All_Solutions/SBS96_3_Signatures/Signatures/SBS96_S3_Signatures.txt"
-activities=dir_inp+"Results_scenario_8/SBS96/All_Solutions/SBS96_3_Signatures/Activities/SBS96_S3_NMF_Activities.txt"
-samples=dir_inp+"Input_scenario_8/Samples.txt"
-output="output_example/"
-sigs= "COSMIC_v3_SBS_GRCh37_noSBS84-85.txt" #Custom Signature Database
+dir_inp     = spa.__path__[0]+'/data/Examples/'
+signatures  = dir_inp+"Results_scenario_8/SBS96/All_Solutions/SBS96_3_Signatures/Signatures/SBS96_S3_Signatures.txt"
+activities  = dir_inp+"Results_scenario_8/SBS96/All_Solutions/SBS96_3_Signatures/Activities/SBS96_S3_NMF_Activities.txt"
+samples     = dir_inp+"Input_scenario_8/Samples.txt"
+output      = "output_example/"
+sigs        = "COSMIC_v3_SBS_GRCh37_noSBS84-85.txt" #Custom Signature Database
 
 #Analysis of SP Assignment 
-Analyze.cosmic_fit( samples, output, signatures=None,signature_database=sigs,genome_build="GRCh37", verbose=False)
+Analyze.cosmic_fit( samples, 
+                    output, 
+                    signatures=None,
+                    signature_database=sigs,
+                    genome_build="GRCh37", 
+                    verbose=False,
+                    collapse_to_SBS96=False,
+                    signature_subgroups=signature_subgroups,
+                    make_plots=True)
 
 ```
 ## <a name="copyright"></a> Copyright

README.md

@@ -1,11 +1,11 @@
 from SigProfilerAssignment import decomposition as decomp
 
-def decompose_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05, nnls_remove_penalty=0.01, initial_remove_penalty=0.05,genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None):
+def decompose_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05, nnls_remove_penalty=0.01, initial_remove_penalty=0.05,genome_build="GRCh37",  make_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None,new_signature_thresh_hold=0.8,signature_subgroups=None):
 
-                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_decomposition_plots=make_decomposition_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= True,denovo_refit_option=False,cosmic_fit_option=False,devopts=devopts)
+                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_plots=make_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= True,denovo_refit_option=False,cosmic_fit_option=False,devopts=devopts,new_signature_thresh_hold=new_signature_thresh_hold,signature_subgroups=signature_subgroups)
 
-def denovo_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05,nnls_remove_penalty=0.01, initial_remove_penalty=0.05, genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None):
-                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_decomposition_plots=make_decomposition_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= False,denovo_refit_option=True,cosmic_fit_option=False,devopts=devopts)
+def denovo_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05,nnls_remove_penalty=0.01, initial_remove_penalty=0.05, genome_build="GRCh37",  make_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None,new_signature_thresh_hold=0.8):
+                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_plots=make_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= False,denovo_refit_option=True,cosmic_fit_option=False,devopts=devopts)
 
-def cosmic_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05, nnls_remove_penalty=0.01, initial_remove_penalty=0.05,genome_build="GRCh37",  make_decomposition_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None):
-                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_decomposition_plots=make_decomposition_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= False,denovo_refit_option=False,cosmic_fit_option=True,devopts=devopts)
+def cosmic_fit(samples,  output, signatures=None, signature_database=None,nnls_add_penalty=0.05, nnls_remove_penalty=0.01, initial_remove_penalty=0.05,genome_build="GRCh37",  make_plots=True, collapse_to_SBS96=True,connected_sigs=True, verbose=False,devopts=None,signature_subgroups=None):
+                decomp.spa_analyze(samples=samples,  output=output, signatures=signatures, signature_database=signature_database,nnls_add_penalty=nnls_add_penalty, nnls_remove_penalty=nnls_remove_penalty, initial_remove_penalty=initial_remove_penalty,genome_build=genome_build,  make_plots=make_plots, collapse_to_SBS96=collapse_to_SBS96,connected_sigs=connected_sigs, verbose=verbose,decompose_fit_option= False,denovo_refit_option=False,cosmic_fit_option=True,devopts=devopts,signature_subgroups=signature_subgroups)