cplaisier/oncomerge repository overview

⁠OncoMerge

Software to integrate somatic protein affecting mutations (PAMs) gene fusions, and copy number alterations (CNAs) for downstream computational analyses.

⁠Citation

Striker SS, Wilferd SF, Lewis EM, O'Connor SA, Plaisier CL. Systematic integration of protein-affecting mutations, gene fusions, and copy number alterations into a comprehensive somatic mutational profile.⁠ Cell Rep Methods. 2023 Apr 4;3(4):100442. doi: 10.1016/j.crmeth.2023.100442. PMID: 37159661; PMCID: PMC10162952.

⁠Docker instance

Includes all dependencies and a recent version of OncoMerge already downloaded.

⁠Dependencies

These Python packages need to be installed to run OncoMerge:

• pandas
• numpy
• statsmodels (2.1.0)
• tqdm

⁠Pull Docker image

Download the Dockerhub image to your computer/server:

docker pull cplaisier/oncomerge

⁠Running Docker image

Instantiate the image:

docker run -it -v "<local_files>:/files"  cplaisier/oncomerge

⁠OncoMerge input

⁠Summary

• PAM:
  • Somatic mutation matrix
  • MutSigCV2 result file
• Fusion:
  • PRADA output file
• CNA:
  • GISTIC2 output files:
    • Amp file
    • Del file
    • all_data_by_genes file

⁠Inputs to OncoMerge

An essential first step in OncoMerge is loading up and binarizing the somatic mutation data. The somatic mutation data comprised of four primary matrices: 1) PAMs, 2) fusions, 3) CNA amplifications (CNAamps), and 4) CNA deletions (CNAdels) (Figure 1). In addition, two derivative matrices Act and LoF are created by merging the PAM with the CNAamps or CNAdels matrices, respectively (Figure 1). All files are formatted as comma-separated values (CSV) files with genes as rows and patients as columns unless otherwise noted.

• PAM matrix - The matrix values are [0 or 1]: zero indicates the gene is not mutated in a patient tumor, and one indicates the gene is mutated in a patient tumor.
• Fusion matrix - The matrix values are [0 or 1]: zero indicates no gene fusion in a patient tumor, and one indicates the gene fused to another genomic locus in a patient tumor.
• CNAamp and CNAdel matrices – The all_thresholded_by_genes.csv GISTIC output file is used to populate the CNAamp and CNAdel matrices. The all_thresholeded_by_genes matrix values range from -2 and have no positive bound, and the values indicate the copy number relative to the background. A cutoff of greater than or equal to 2 was used to identify deep amplifications and less than or equal to -2 for deep deletions. Only deep amplifications or deletions were included in these studies due to heterogeneity of cell types and tumor biopsy purity. Oncomerge allows this threshold to be modified through a command line parameter ('-gt' or '--gistic-threshold').
  • CNAamp matrix – The matrix values are [0 or 1]: zero indicates a gene is not amplified in a patient tumor, and one indicates the gene is amplified in a patient tumor.
  • CNAdel matrix – The matrix values are [0 or 1]: zero indicates a gene is not deleted in a patient tumor, and one indicates a gene is deleted in a patient tumor.
• Act matrix – The Act matrix is the bitwise OR combination of the PAM, Fusion, and CNAamp matrices. The Act matrix has genes as rows and patients as columns. The matrix values are [0 or 1]: zero indicates the gene is not mutated or amplified in a patient tumor, and one indicates the gene is either mutated, fused, amplified, or some combination in a patient tumor.
• LoF matrix – The LoF matrix is the bitwise OR combination of the PAM, Fusion, and CNAdel matrices. The LoF matrix has genes as rows and patients as columns. The matrix values are [0 or 1]: zero indicates the gene is not mutated or deleted in a patient tumor, and one indicates the gene is either mutated, fused, deleted, or some combination in a patient tumor.\

⁠Usage

From the command line -h or --help will provide a list of all possible parameters. Parameters can be given either as a config file formatted in JSON as entries with command line argument names as keys in a dictionary or as named command line parameters:

usage: oncoMerge.py [-h] [-cf CONFIG_FILE] [-gp GISTIC_PATH] [-df DEL_FILE] [-af AMP_FILE] [-gdf GENE_DATA_FILE]
                    [-aaf ALTERNATE_ANNOTATION_FILE] [-ln LABEL_NAME] [-tf THRESH_FILE] [-gt GISTIC_THRESHOLD] [-pam PAM_FILE]
                    [-mscv MUTSIG2CV_FILE] [-fus FUSIONS_FILE] [-op OUTPUT_PATH] [-mmf MIN_MUT_FREQ] [-pq PERM_QV] [-sp]
                    [-lp LOAD_PERMUTATION] [-mlg MIN_LOCI_GENES] [-mpf MIN_PAM_FREQ] [-tcga TCGA] [-bl BLOCKLIST]

OncoMerge merges patient Protein Affecting Mutations (PAMs) and Copy Number Alterations (CNAs) into a unified mutation matrix.

optional arguments:
  -h, --help            show this help message and exit
  -cf CONFIG_FILE, --config_file CONFIG_FILE
                        Path to JSON encoded configuration file, overrides command line parameters using argument names as entries in a JSON formatted dictionary
  -gp GISTIC_PATH, --gistic_path GISTIC_PATH
                        Path to GISTIC output folder
  -df DEL_FILE, --del_file DEL_FILE
                        Path to GISTIC deletion file (default = del_genes.conf_99.txt)
  -af AMP_FILE, --amp_file AMP_FILE
                        Path to the GISTIC amplification file (default = amp_genes.conf_99.txt)
  -gdf GENE_DATA_FILE, --gene_data_file GENE_DATA_FILE
                        Path to the GISTIC gene data file (default = all_data_by_genes.txt)
  -aaf ALTERNATE_ANNOTATION_FILE, --alternate_annotation_file ALTERNATE_ANNOTATION_FILE
                        Supply alternate annotation file to convert gene symbols to Entrez IDs (default does not import
                        alternate annotation file and instead uses conversion embedded in GISTIC output files).
  -ln LABEL_NAME, --label_name LABEL_NAME
                        Label for Entrez ID column in GISTIC gene data file (default = 'Gene ID')
  -tf THRESH_FILE, --thresh_file THRESH_FILE
                        Path to the GISTIC all_thresholded file (default = all_thresholded.by_genes.txt)
  -gt GISTIC_THRESHOLD, --gistic_threshold GISTIC_THRESHOLD
                        Cutoff value for amplifications and deletions applied to the GISTIC all_thresholded file (default = 2)
  -pam PAM_FILE, --pam_file PAM_FILE
                        Path to the protein affecting mutation (PAM) file (CSV matrix where columns are patients and genes are
                        rows) [0 = not mutated, and 1 = mutated]
  -mscv MUTSIG2CV_FILE, --mutsig2cv_file MUTSIG2CV_FILE
                        Path to a MutSig2CV output file
  -fus FUSIONS_FILE, --fusions_file FUSIONS_FILE
                        Path to the gene fusions file (CSV matrix where columns are patients and genes are rows) [0 = not
                        fused, and 1 = fused]
  -op OUTPUT_PATH, --output_path OUTPUT_PATH
                        Path you would like to output OncoMerged files (default = current directory)
  -mmf MIN_MUT_FREQ, --min_mut_freq MIN_MUT_FREQ
                        Minimum frequency of mutation (range = 0-1; default = 0.05)
  -pq PERM_QV, --perm_qv PERM_QV
                        Permuted p-value FDR BH corrected cutoff (default = 0.1)
  -sp, --save_permutation
                        Run and save out permutation analysis to be used for comparability in another OncoMerge run (default
                        off)
  -lp LOAD_PERMUTATION, --load_permutation LOAD_PERMUTATION
                        Do not run permutation anlaysis and load permutation anlaysis from previous run (default off)
  -mlg MIN_LOCI_GENES, --min_loci_genes MIN_LOCI_GENES
                        Minimum number of genes in loci to apply maximum final frequency filter (default = 10)
  -mpf MIN_PAM_FREQ, --min_pam_freq MIN_PAM_FREQ
                        Minimum PAM frequency (default = 0.01)
  -tcga TCGA, --tcga TCGA
                        Clip gistic TCGA names.
  -bl BLOCKLIST, --blocklist BLOCKLIST
                        List of patients (one per line) to exclude for frequency calculations.

⁠Running on TCGA bladder carcinoma (BLCA) test data from figshare

Clone the OncoMerge github directory. Download and untar the TCGA BLCA dataset from figshare inside the OncoMerge github directory:

git clone https://github.com/plaisier-lab/OncoMerge.git
cd OncoMerge
wget https://figshare.com/ndownloader/files/40671497 -O test.tgz
tar xvzf test.tgz

Make a directory to hold the output for OncoMerge:

mkdir output

⁠Run with command line parameters:

Then run this command to execute OncoMerge on the TCGA BLCA test data:

python3 oncoMerge.py \
            -gp test_data/GISTIC/BLCA \
            -aaf test_data/OncoMerge_input_g2e_converter.csv \
            -ln "Locus ID" \
            -pam test_data/PAM/BLCA_somMutMC3.csv \
            -mscv test_data/MutSig2cv/BLCA_sig2cv.csv \
            -fus test_data/FUSIONS/BLCA_fusions.csv \
            -op output_BLCA \
            -pq 0.1 \
            -mlg 10 \
            -tcga True \
            -bl test_data/blocklist/blocklist_29850653_29625053.csv

⁠Run with configuration json file:

Make a json file with configuration parameters:

Then run this command to execute OncoMerge on the TCGA BLCA test data:

python3 oncoMerge.py -cf test.json

⁠Output

OncoMerge provides four output files that provide valuable information about the integration process and the final integrated mutation matrix that can be used in downstream studies. Here is a brief description of each file and its contents:

• oncoMerge_mergedMuts.csv – The integrated mutation matrix is comprised of genes (rows) by patient tumors (columns) of mutation status after integration by OncoMerge. The matrix values are [0 or 1]: zero indicates that the gene is not mutated in a patient tumor, and one indicates that the gene was mutated in a patient tumor.
• oncoMerge_CNA_loci.csv – A list of the genes mapping to each CNAamp or CNAdel locus included in the OncoMerge integrated mutation matrix.
• oncoMerge_ActLofPermPV.csv – List of all significant Act and LoF genes, their OncoMerge mutation role, frequency, empirical p-value, and empirical q-value. This output is before the application of the low-pass frequency filter.
• oncoMerge_summaryMatrix.csv – Matrix of genes (rows) by all information gathered by OncoMerge.

⁠Optional output

To aid in comparisons between runs, we provide the save permutation option ('-sp' or '--save_permutation') to output permutation results so that the same permuted distribution can be used with different parameters in separate runs. We also provide the load permutation option ('-lp' or '--load_permutation') to load up the permuted distribution from a previous run. The permuted distributions are saved in the following files if requested:

• oncomerge_ampPerm.npy, oncomerge_delPerm.npy – Snapshot of the non-deterministic permutation results from combining PAM, Fusion, and CNAamp or PAM, Fusion, and CNAdel frequencies, respectively.