1. Input files: The input to __main__.py is either
   • two tab-delimited text files -- one for variant read data and one for coverage data. Please see the files input/Makohon2017/Pam03_mutant_reads.txt and input/Makohon2017/Pam03_phredcoverage.txt included in this repository for examples.
   • VCF-files of all samples
2. Type the following command to run the tool: treeomics -r <mut-reads table> -s <coverage table> where <mut-reads table> is the path to a tab-separated-value file with the number of reads reporting a variant (row) in each sample (column) and <coverage table> is the path to a tab-separated-value file with the sequencing depth at the position of this variant in each sample.

Usage:

$ treeomics -r <mut-reads table> -s <coverage table> | -v <vcf file> | -d <vcf file directory>

Optional parameters:

• -e : Sequencing error rate e in the Bayesian inference model (default 1.0%)

• -a : Maximum VAF for an absent variant f_absent before considering the estimated purity (default 5%)

• -z : Prior probability for a variant being absent *c₀ (default 0.5).

• -o

  :

  Provide different output directory (default output)

• -n : If a normal sample is provided, variants significantly present in the normal are removed. Additional normal samples can be provided via a space-separated enumeration. E.g. -n FIRSTNORMALSAMPLE SECONDNORMALSAMPLE

• -x : Space-separated enumeration of sample names to exclude from the analysis. E.g. -x FIRSTEXCLUDEDSAMPLE SECONDEXCLUDEDSAMPLE

• --pool_size : Number of best solutions explored by ILP solver to assess the support of the inferred branches (default 1000)

• -b : Number of bootstrapping samples (default 0); Generally using the solution pool instead of bootstrapping seems to be the more efficient way to assess confidence.

• -u: Enables subclone detection (default False)

• -c : Minimum median coverage of a sample to be considered (default 0)

• -f : Minimum median mutant allele frequency of a sample to be considered (default 0)

• -p : False-positive rate of conventional binary classification (only relevant for artifact comparison)

• -i : Targeted false-discovery rate of conventional binary classification (only relevant for artifact comparison)

• -y : Minimum coverage for a powered absent variant (only relevant for artifact comparison)

• -g : provide used reference genome for mutation consequence annotation; supporting grch37 (for hg19; default), grch36 (for hg18), and grch38 (for hg38); E.g. -g grch38

• -t : Maximum running time for CPLEX to solve the MILP (in seconds, default None). If not None, the obtained solution is no longer guaranteed to be optimal

• --threads=<N> Maximal number of parallel threads that will be invoked by CPLEX (0: default, let CPLEX decide; 1: single threaded; N: uses up to N threads)

• -l <max no MPS>: Maximum number of considered mutation patterns per variant (default None). If not None, the obtained solution is no longer guaranteed to be optimal

• --driver_genes=<path to file> Path to CSV file with names of putative driver genes highlighted in inferred phylogeny (default --driver_genes=../input/Tokheim_drivers_union.csv)

• --wes_filtering Removes intronic and intergenic variants in WES data (default False)

• --common_vars_file Path to file with common variants in normal samples and therefore removed from analysis (default None)

• --no_plots Disables generation of X11 depending plots (useful for benchmarking; default plots are generated plots)

• --no_tikztrees Disables generation of latex trees which do not depend on X11 (default latex trees are generated tikztrees)

• --benchmarking Generates mutation matrix and mutation pattern files that can be used for automatic benchmarking of silico data (default False)

• --include Provide a list of sample names that should be analyzed (e.g., --include PT1 PT2 PT3 PT4)

• --purities Provide a list of externally estimated sample purities (e.g., --purities 0.7 0.3 0.9 0.8). Requires --include argument with the same ordering of samples.

• --min_var_reads <> and/or --min_vaf <> Minimum VAF of a variant in at least one of the provided samples with a minimum number of variant reads

• --min_var_cov <> minimum coverage of a variant across all samples, otherwise the variant is excluded

Default parameter values as well as output directory can be changed in treeomics/settings.py. Moreover, the settings.py provides more options an annotation of driver genes and configuration of plot output names. All plots, analysis and logging files, and the HTML report will be in this output directory.

Optional input:

• Driver gene annotation: Treeomics highlights any non-synonymous or splice-site variants (if VarCode is available, otherwise all) in putative driver genes given in a CSV-file under DRIVER_PATH in treeomics/settings.py. As default list, the union of reported driver genes by 20/20+, TUSON, and MutsigCV from Tokheim et al. (PNAS, 2016) is used (see input/Tokheim_drivers_union.csv). Any CSV-file can be used as long as there is column named 'Gene_Symbol'. Variants in these provided genes will be highlighted in the HTML report as well as in the inferred phylogeny.
• Cancer Gene Census (CGC) annotation: Variants that have been identified as likely drivers in the provided genes (under DRIVER_PATH) will be check if they occurred in the reported region in the given CSV-file (default input/cancer_gene_census_grch37_v80.csv; CGC version 80, reference genome hg19).

Example 1:

$ treeomics -r input/Makohon2017/Pam03_1-10_mutant_reads.txt -s input/Makohon2017/Pam03_1-10_phredcoverage.txt -n Pam03N3 -e 0.005

Reconstructs the phylogeny of pancreatic cancer patient Pam03 based on targeted sequencing data of 5 distinct liver metastases, 3 distinct lung metastases, and 2 samples of the primary tumor.

Example 2:

$ treeomics -r input/Bashashati2013/Case5_mutant_reads.txt -s input/Bashashati2013/Case5_coverage.txt -e 0.01

Reconstructs the phylogeny of the high-grade serous ovarian cancer of Case 5 in Bashashati et al. (2013).

Example 3:

$ treeomics -v input/example.vcf