SigProfilerTopography allows evaluating the effect of chromatin organization, histone modifications, transcription factor binding, DNA replication, and DNA transcription on the activities of different mutational processes. SigProfilerTopography elucidates the unique topographical characteristics of mutational signatures. The tool seamlessly integrates with other SigProfiler tools including SigProfilerMatrixGenerator, SigProfilerSimulator, and SigProfilerAssignment. Detailed documentation can be found at: https://osf.io/5unby/wiki/home/

SigProfilerTopography provides topography analyses for mutations such as

• Single Base Substitutions (SBS)
• Doublet Base Substitutions (DBS)
• Small insertions and deletions, indels (ID)

and carries out following analyses:

• Epigenomics Occupancy (e.g.: Histone Modifications, Transcription Factors, Open Chromatin Regions)
• Nucleosome Occupancy
• Replication Timing
• Replication Strand Asymmetry
• Transcription Strand Asymmetry
• Genic versus Intergenic Regions
• Strand-coordinated Mutagenesis

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

QUICK START GUIDE

This section will guide you through the minimum steps required to run SigProfilerTopography:

1. For most recent stable PyPI version of this tool, install the python package using pip:

   $ pip install SigProfilerTopography
   

   If you have installed SigProfilerTopography before, upgrade using pip:

   $ pip install SigProfilerTopography --upgrade
   

2. Imports the example data that is provided by SigProfilerTopography. This data can be used to run the example program and ensure that the environment is set up.

   >>> from SigProfilerTopography import Topography as topography
   >>> topography.install_example_data()

   Imports 21BRCA.zip under the current working directory. Once 21BRCA.zip has been downloaded, unzip the file. The unzipped 21BRCA folder contains two folders: 21BRCA_vcfs and 21BRCA_probabilities. The folder 21BRCA_vcfs contains 21 VCF files (one per each breast cancer sample) in GRCh37 and 21BRCA_probabilities` contains probability matrix files for single base substitutions and doublet base substitutions.

3. 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.

4. Imports the nucleosome library file that is necessary for nucleosome occupancy analyses. Next, choose the genome that you would like to import:

   >>> from SigProfilerTopography import Topography as topography
   >>> topography.install_nucleosome("GRCh37")

   By default, install_nucleosome imports nucleosome data of K562 cell line for GRCh37 and GRCh38 genome assemblies.

5. Imports the open chromatin library file that is necessary for epigenomics analyses. Next, choose the genome that you would like to import:

   >>> from SigProfilerTopography import Topography as topography
   >>> topography.install_atac_seq("GRCh37")

   By default, install_atac_seq imports open chromatin data of breast epithelium tissue for GRCh37 and left lung tissue for GRCh38.

6. Imports the replication timing library file that is necessary for replication timing analyses. Next, choose the genome that you would like to import:

   >>> from SigProfilerTopography import Topography as topography
   >>> topography.install_repli_seq("GRCh37")

   By default, install_repli_seq imports replication time data of MCF7 and IMR90 for GRCh37 and GRCh38, respectively.

7. Conducts topography analyses for your samples. Here is an example of a call to runAnalyses that generates all of the different analyses.

   >>> from SigProfilerTopography import Topography as topography
   
   >>> genome = "GRCh37"
   >>> inputDir = "path/to/21BRCA_vcfs"
   >>> outputDir = "path/to/results"
   >>> jobname = "21BRCA_SPT"
   >>> numofSimulations = 5
   
   >>> topography.runAnalyses(genome, 
                      inputDir, 
                      outputDir, 
                      jobname, 
                      numofSimulations, 
                      epigenomics=True,
                      nucleosome=True, 
                      replication_time=True, 
                      strand_bias=True, 
                      processivity=True)

   If probability files are not provided, SigProfilerTopography utilizes SigProfilerAssignment by default to attribute the activities of known reference mutational signatures from the Catalogue Of Somatic Mutations In Cancer (COSMIC) database to each examined sample.

8. Here is an example of a call to runAnalyses with probability files using the 21 VCF files located in the subfolder 21BRCA_vcfs as input and providing the probability files in the subfolder 21BRCA_probabilities.

   >>> from SigProfilerTopography import Topography as topography
   
   >>> genome = "GRCh37"
   >>> inputDir = "path/to/21BRCA_vcfs"
   >>> outputDir = "path/to/results"
   >>> jobname = "21BRCA_SPT_with_probability_matrices"
   >>> numofSimulations = 5
   >>> sbs_probability_file = "path/to/21BRCA_probabilities/COSMIC_SBS96_Decomposed_Mutation_Probabilities.txt"
   >>> dbs_probability_file = "path/to/21BRCA_probabilities/COSMIC_DBS78_Decomposed_Mutation_Probabilities.txt"
   
   >>> topography.runAnalyses(genome, 
                      inputDir, 
                      outputDir, 
                      jobname, 
                      numofSimulations, 
                      sbs_probabilities = sbs_probability_file,
                      dbs_probabilities = dbs_probability_file,
                      epigenomics=True,
                      nucleosome=True, 
                      replication_time=True, 
                      strand_bias=True, 
                      processivity=True)

   SigProfilerTopography utilizes probability matrix files containing the probability of each signature to cause a specific mutation type in a cancer sample.

View the table below for the full list of runAnalyses parameters.

PARAMETERS

SigProfilerTopography Output To learn about the output, please visit https://osf.io/5unby/wiki/home/

Otlu B, Alexandrov LB: Evaluating topography of mutational signatures with SigProfilerTopography. BioRxiv 2024, https://doi.org/10.1101/2024.01.08.574683.

Otlu B, Diaz-Gay M, Vermes I, Bergstrom EN, Zhivagui M, Barnes M, Alexandrov LB: Topography of mutational signatures in human cancer. Cell Rep 2023, https://doi.org/10.1016/j.celrep.2023.112930.

This software and its documentation are copyright 2018 as a part of the SigProfiler project. The SigProfilerTopography 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.

Please address any queries or bug reports to Burcak Otlu at burcakotlu@eng.ucsd.edu