DOCSEARCHbyAlgolia
Submit Docs

SigProfilerExtractor

repository·master·Indexed 41 days ago

https://github.com/sigprofilersuite/sigprofilerextractor

A tool for the de novo extraction of mutational signatures from matrix-format data, identifying signature counts, activities, and mutation probabilities. It supports multiple input types including VCF files, mutation matrices, BEDPE files, and segmentation files. Key features include the sigProfilerExtractor() API for signature extraction, estimate_solution() for determining optimal signature rank based on stability metrics, and plotActivity.py for generating activity stacked bar plots.

Tokens
6.2K
Snippets
17
Records
38
Agent score
51%

What's inside SigProfilerExtractor

  1. Overview of SigProfilerExtractor

    master

    SigProfilerExtractor is a Python framework designed for the de novo extraction of mutational signatures from data provided in a matrix format.

    Key capabilities include:

    • Identifying the number of operative mutational signatures.
    • Determining signature activities within each sample.
    • Calculating the probability of each signature causing specific mutation types in cancer samples.

    The tool is designed to integrate seamlessly with other tools in the SigProfiler ecosystem, specifically SigProfilerMatrixGenerator and SigProfilerPlotting.

  2. Understand the Suggested_Solution output directory structure

    master

    The Suggested_Solution directory contains specialized outputs that differ from the standard All_Solutions output. It is organized into two primary subdirectories:

    1. COSMIC_SBS96_Decomposed_Solution: Contains files mapping de novo extracted signatures to COSMIC signatures.
    2. De_Novo_Solution: Contains mutation probabilities and assignment logs for de novo signatures.

    For files that are common to both Suggested_Solution and All_Solutions, refer to the Output - All Solutions documentation.

  3. Understand the All_Solutions directory structure

    master
    The All_Solutions directory contains the results of the signature extraction process, organized by the number of signatures identified (e.g., SBS96_1_Signatures through SBS96_10_Signatures). Each solution subdirectory contains three main subdirectories: Activities, Signatures, and Solution_Stats. This structure is consistent across different mutational contexts.

  4. Understand the Mutational Context subdirectory structure

    master

    For every mutational context processed (e.g., SBS96, ID83, DBS78), SigProfilerExtractor creates a dedicated subdirectory. All context-specific results follow the same internal structure:

    • All_Solutions/: Contains extraction results for every rank within the input range.
    • Suggested_Solution/: Contains the single optimal solution identified by the tool.
    • All_solutions_stat.csv: A statistical record of reconstruction error and process stability.
    • [Context]_selection_plot.pdf: A visualization (e.g., SBS96_selection_plot.pdf) showing the relationship between mean sample cosine distance and average stability, with a vertical gray bar indicating the optimal number of signatures.
    • Samples.txt: A matrix of mutation counts per sample for that specific context.

  5. Understand the SigProfilerExtractor output structure

    master

    SigProfilerExtractor organizes its results within the specified output/ directory. The output is hierarchically grouped by mutation context, such as SBS96/, DBS78/, ID83/, CNV48/, or SV32/.

    Inside each mutation context folder, the following files and directories are generated:

    • All_Solutions/: Contains per-rank outputs, including signatures, activities, plots, and statistics for every rank evaluated.
    • Suggested_Solution/: Contains the single selected solution. If COSMIC decomposition was enabled, this folder also includes the COSMIC decomposition outputs.
    • All_solutions_stat.csv: A CSV file containing rank-selection statistics.
    • Samples.txt: A text file containing the input matrix used during the extraction process.

  7. Use the SigProfilerExtractor CLI

    master

    SigProfilerExtractor can be invoked via the command line using the SigProfilerExtractor sigprofilerextractor entrypoint. The command requires an input type, an output directory, and the path to the input data, followed by optional configuration flags.

    Command Syntax: SigProfilerExtractor sigprofilerextractor <input_type> <output> <input_data> [options]

    Input Types:

    • matrix: Used when providing a text file (e.g., Samples_SBS.txt) containing mutation matrices.
    • vcf: Used when providing a directory containing VCF files.

    Common Options:

    • --reference_genome: Specify the genome assembly (e.g., GRCh37) when using VCF input.
    • --minimum_signatures: Set the minimum number of signatures to extract.
    • --maximum_signatures: Set the maximum number of signatures to extract.
    # Example using a mutation matrix
SigProfilerExtractor sigprofilerextractor matrix example_output /path/to/Samples_SBS.txt --minimum_signatures 1 --maximum_signatures 3

# Example using VCF files
SigProfilerExtractor sigprofilerextractor vcf example_output /path/to/vcf_folder --reference_genome GRCh37 --minimum_signatures 1 --maximum_signatures 3

  10. Download example dataset 21BRCA

    master

    To follow the quick start example, download the 21BRCA.zip dataset containing somatic mutational data from 21 breast cancer genomes.

    FTP Location: ftp://alexandrovlab-ftp.ucsd.edu/pub/tools/SigProfilerExtractor/Example_data/

    Using wget (Unix/OS X):

    $ wget ftp://alexandrovlab-ftp.ucsd.edu/pub/tools/SigProfilerExtractor/Example_data/21BRCA.zip

    After downloading, unzip the file. The 21BRCA folder will contain:

    • 21BRCA.txt: A mutational matrix using SBS-96 classification.
    • 21BRCA_vcf/: A directory containing 21 VCF files (one per sample).

  11. Run sigProfilerExtractor with VCF files

    master

    To extract mutational signatures from VCF files, use the sigProfilerExtractor function. You can provide the path to the folder containing your VCF samples as input.

    Note: The execution process may take several hours depending on the size of your data. Ensure you allow sufficient time for completion.

  12. Install a reference genome

    master

    SigProfilerExtractor requires a reference genome to function. You can install supported reference genomes using the install function from SigProfilerMatrixGenerator.

    Supported reference genomes include:

    • GRCh37
    • GRCh38
    • mm9
    • mm10
    from SigProfilerMatrixGenerator import install as genInstall
genInstall.install('GRCh37')