SigProfilerTopography

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
   
   >>> if __name__ == "__main__":
           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"
   
   >>> if __name__ == "__main__":
           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.

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

Replication Time Biosamples For GRCh37 and GRCh38, SigProfilerTopography provides Repli-seq files of the biosamples listed in the table below, which are the valid parameter values for replication_time_biosample.

• REPLICATION TIMING and REPLICATION STRAND ASYMMETRY

  • By default, SigProfilerTopography carries out replication timing and replication strand asymmetry analyses using Repli-seq of MCF7 and IMR90 cell line for GRCh37 and GRCh38, respectively.

  • If you want to run SigProfilerTopography with Repli-seq of e.g., HELAS3 cell line, you may first install replication timing data for the genome of interest e.g.: GRCh37 as follows:

    $ python
    >> from SigProfilerTopography import Topography as topography
    >> topography.install_repli_seq('GRCh37', 'HELAS3')
    

  • Then you have to include replication_time_biosample='HELAS3' in the runAnalyses call as follows:

    >>> 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"
    
    >>> if __name__ == "__main__":
                topography.runAnalyses(genome,
                            inputDir,
                            outputDir,
                            jobname,
                            numofSimulations,
                            sbs_probabilities = sbs_probability_file, 
                            dbs_probabilities = dbs_probability_file, 
                            replication_time_biosample='HELAS3',
                            epigenomics=True,
                            nucleosome=True, 
                            replication_time=True, 
                            strand_bias=True, 
                            processivity=True)
    

  • If you do not install replication timing file before the run, SigProfilerTopography downloads replication timing files from ftp://alexandrovlab-ftp.ucsd.edu/ under .../SigProfilerTopography/lib/replication/ for the replication_time_biosample of interest during runtime which requires ~20-100 MB of storage.

  • If you have a replication timing file, you can set the replication_time_signal_file and run replication timing and replication strand asymmetry analyses using your own replication timing file.

    We require a tab-separated file with four columns for replication_time_signal_file. No header line is required. The columns should contain the following information:

    1. Chromosome (e.g., chr1)
    2. Start position (e.g., 10000)
    3. End position (e.g., 15000)
    4. Signal value (e.g., 1.0343)

    Then you have to set replication_time_signal_file in the runAnalyses call as follows:

    >>> 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"
    
    >>> if __name__ == "__main__":
                topography.runAnalyses(genome,
                            inputDir,
                            outputDir,
                            jobname,
                            numofSimulations,
                            sbs_probabilities = sbs_probability_file, 
                            dbs_probabilities = dbs_probability_file, 
                            replication_time_signal_file="path/to/replication_timing_file",
                            epigenomics=True,
                            nucleosome=True, 
                            replication_time=True, 
                            strand_bias=True, 
                            processivity=True)
    

  • SigProfilerTopography, annotates each mutation with its replication strand. Replication strand can be one of the below:

    A: Lagging
    E: Leading
    U: Unknown
    B: Bidirectional (Both lagging and leading can happen for long indels).

    You can reach them under outputDir/jobname/data/chrbased, if you set delete_chrbased_files=False as follows.

    >>> 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"
    
    >>> if __name__ == "__main__":
                topography.runAnalyses(genome,
                            inputDir,
                            outputDir,
                            jobname,
                            numofSimulations,
                            sbs_probabilities = sbs_probability_file, 
                            dbs_probabilities = dbs_probability_file, 
                            replication_time_biosample="T47D",
                            epigenomics=True,
                            nucleosome=True, 
                            replication_time=True, 
                            strand_bias=True, 
                            processivity=True,
                            delete_chrbased_files=False)

Citation

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.

Copyright

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.

Contact Information

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