Metadata-Version: 2.4 Name: GS-PRACTICE Version: 1.1.0 Summary: Tumor genomic subtyping using mutational signatures Home-page: https://github.com/shirotak/GS-PRACTICE Author: shirotak Author-email: tshiro@kuhp.kyoto-u.ac.jp License: GPLv2 with a non-commercial-use restriction; see LICENSE Project-URL: Bug Tracker, https://github.com/shirotak/GS-PRACTICE/issues Classifier: Programming Language :: Python :: 3 Classifier: License :: Other/Proprietary License Classifier: Operating System :: OS Independent Requires-Python: >=3.11 Description-Content-Type: text/markdown License-File: LICENSE Requires-Dist: numpy>=2.4 Requires-Dist: scipy>=1.17 Requires-Dist: pandas>=3.0 Requires-Dist: scikit-learn>=1.8 Requires-Dist: umap-learn>=0.5.12 Requires-Dist: numba>=0.66 Requires-Dist: pyfaidx>=0.9 Requires-Dist: matplotlib>=3.10 Dynamic: author Dynamic: author-email Dynamic: classifier Dynamic: description Dynamic: description-content-type Dynamic: home-page Dynamic: license Dynamic: license-file Dynamic: project-url Dynamic: requires-dist Dynamic: requires-python Dynamic: summary # GS-PRACTICE (Genomic Subtyping and Predictive Response Analysis for Cancer Tumor ICi Efficacy) Tumor genomic subtyping tool based on mutational signatures for cancer samples. See [the corresponding paper](https://www.medrxiv.org/content/10.1101/2021.10.03.21264330v2) for details. ___ Overview of the pipeline ___ ## Requirements ### Python >= 3.11 - numpy - scipy - pandas - scikit-learn - umap-learn - numba - pyfaidx - matplotlib Please see `requirements.txt` for detailed versions. As of v1.1, GS-PRACTICE is implemented entirely in Python: it no longer depends on R, Bioconductor, or rpy2. The 96-trinucleotide mutation matrix (previously built by R's `MutationalPatterns`) is now built directly from VCF/MAF input using a user-supplied reference FASTA (via `pyfaidx`), and signature fitting uses non-negative least squares (`scipy.optimize.nnls`) against the same COSMIC (v2) signature reference used in v1.0. ___ ## Installation To avoid package dependency problems, I recommend installation in a virtual environment created with anaconda, miniconda, miniforge, pyenv etc. For example, ``` conda create -n GSP python=3.11 conda activate GSP ``` After downloading this repository, ``` cd GS-PRACTICE pip install . ``` Or, from [PyPI](https://pypi.org/project/GS-PRACTICE), ``` pip install GS-PRACTICE ``` Then, ``` pip install -r requirements.txt ``` ___ ## Preparations #### Reference genome FASTA You need a reference genome FASTA file matching the genome build of your input (GRCh38/hg38 or GRCh37/hg19), passed via `-r/--reference`. Chromosome naming with or without a `chr` prefix is handled automatically. An index (`.fai`) is generated next to the FASTA on first use if one doesn't already exist. #### Make classifiers in your environment After installing the requirements, you should configure classifiers and umap projector in your environment and save them as pickle files. By default, pickle files named KNN, SVC, RFC, LRC, and UMAP_projector are generated in `gspractice/data` directory. ``` gs-makeclfs ``` ___ ## Usage ``` gs-practice -i {input_file} -r {reference_fasta} -o {output_prefix} ``` ### Input files [VCF file](https://en.wikipedia.org/wiki/Variant_Call_Format)(version >= 4.0) or [MAF file](https://docs.gdc.cancer.gov/Data/File_Formats/MAF_Format/) after somatic mutation calling are accepted. VCF file needs to contain a header starting with "##fileformat=VCFv**". MAF file needs to contain columns named "Hugo_Symbol", "Chromosome", "Start_Position", "End_Position", "Variant_Type", "Reference_Allele", "Tumor_Seq_Allele1", "Tumor_Seq_Allele2" and "Tumor_Sample_Barcode". Only single nucleotide variants (SNVs) are used for signature decomposition; indels are ignored. The default genome version is GRCh38 (hg38), but GRCh37 (hg19) is also accepted if you specify the option `-gv hg19` together with a matching hg19 `-r` reference FASTA. - single VCF file (end with ***.vcf) - list of paths to multiple VCF files (end with ***.list) - MAF file (end with ***.maf) ### Example ``` gs-practice -i input.vcf -r hg38.fa -o output_prefix [-sn samplename ] gs-practice -i vcffiles.list -r hg38.fa -o output_prefix [-snl samplenames.list] gs-practice -i input.maf -r hg38.fa -o output_prefix ``` ### Whole-genome input The bundled classifiers were trained on TCGA whole-*exome* data. If `input_data` is derived from whole-genome sequencing, pass `-eo/--exome_only` to restrict variants to exome capture regions before signature fitting; otherwise the larger genome-wide mutation burden can skew the signature contributions away from what the classifiers expect. By default this uses the Agilent SureSelect Human All Exon V5 regions bundled with the package (matching `-gv/--genome_version`), the same capture kit TCGA's WES pipeline used. Pass `-eb/--exome_bed` with a path to use a different capture or panel BED file instead (3-column chrom/start/end, plain or gzip-compressed). ``` gs-practice -i wgs_sample.vcf -r hg38.fa -o output_prefix -eo ``` `src/gspractice/data/SureSelect_V5_hg{19,38}.bed.gz` contain only the chrom/start/end columns of Agilent's official S04380110 ("SureSelect Human All Exon V5") design files, downloaded from the Agilent SureDesign portal (https://earray.chem.agilent.com/suredesign/, registration required), merged and gzip-compressed to keep the package small. ### Output files ``` {output_prefix}_decomposed.tsv {output_prefix}_prediction.tsv {output_prefix}_umap.png ``` ___ ## Test ``` cd tests bash test_run.sh ``` This will generates the following files in the "tests/output" directory - [cancer_sample01_decomposed.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_sample01_decomposed.tsv) - [cancer_sample01_prediction.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_sample01_prediction.tsv) - [cancer_sample01_umap.png](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_sample01_umap.png) - [cancer_samples_10_decomposed.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_samples_10_decomposed.tsv) - [cancer_samples_10_prediction.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_samples_10_prediction.tsv) - [cancer_samples_10_umap.png](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/cancer_samples_10_umap.png) - [TCGA_mutect2_random100_1_decomposed.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/TCGA_mutect2_random100_1_decomposed.tsv) - [TCGA_mutect2_random100_1_prediction.tsv](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/TCGA_mutect2_random100_1_prediction.tsv) - [TCGA_mutect2_random100_1_umap.png](https://github.com/shirotak/GS-PRACTICE/blob/main/tests/output/TCGA_mutect2_random100_1_umap.png) ___ ## Getting Help ``` gs-practice -h ``` ___ ## Notes - If you want, you can change hyper parameters of classifiers by directly editing the script "gspractice/makeclfs.py". - You may use the tool without installation if you satisfy the requirements. ``` python src/gspractice/makeclfs.py python src/gspractice/run_gspractice.py -h python src/gspractice/run_gspractice.py -i {input_file} -r {reference_fasta} -o {output_prefix} ``` ___ ## Changelog See [CHANGELOG.md](CHANGELOG.md). ___ ## License Copyright (c) 2021 Shiro Takamatsu (Kyoto University). See [LICENSE](https://github.com/shirotak/GS-PRACTICE/blob/main/LICENSE). This software is currently prohibited for commercial use. If you wish to use the Software for commercial or for-profit purposes, please contact [the author](tshiro@kuhp.kyoto-u.ac.jp). ___ ## Citation Mutation burden-orthogonal tumor genomic subtypes delineate responses to immune checkpoint therapy Journal for ImmunoTherpy of Cancer. 2022 Jul;10(7):e004831. http://dx.doi.org/10.1136/jitc-2022-004831. PMID:35868660. DOI:10.1136/jitc-2022-004831.