Package: mach2
MACH2A mathematical framework for inferring migration histories of metastatic cancer from clone phylogeny and the location of extant clones.Table of contentsInstallation-Prerequisite-Install usingpipUsage instruction-I/O formats-Input-Output-Usage1. InstallationPrerequisitesPython-MACH2requires Python 3.7 or newer.ILP solver-MACH2requires an ILP solver installed to solvePMH-TR. CurrentlyMACH2only supportsGurobi optimizer, but we are going to add support for more ILP solvers in the future.MACH2requires a valid Gurobi installation and license key. The location of Gurobi should be present inLD_LIBRARY_PATH(linux) andDYLD_LIBRARY_PATH(macOS) the license key should be saved in the environment variableGRB_LICENSE_KEY.Install usingpipMACH2can easily be installed usingpip, the package installer for Python. Open a terminal or command prompt and run the following command:$ pip install mach2If you want to useMACH2withJupyterLab, you'll need additional dependencies. To install these optional dependencies, you can run the following command:$ pip install mach2[jupyter]Usage InstructionI/O formatsWe describe various formats used byMACH2.Tree file: The tree file contains a list of edges that define the structure of a tree. Each line in the file represents an edge, and the edges should be in the format:vertex1 vertex2. For example:1   2
 2   3
 2   4 
 1   3Labeling file: The labeling file contains the labels assigned to a set of vertices. Each line in the file corresponds to a vertex and the labels are in the format:leaf label. For example:1   A
 2   B
 3   CMulti-graph file: Like tree file, the multi-graph file contains a list of edges that define the structure of the multi-graph. Each line in the file represents the set of edges between any pair of verticesvertex1andvertex2in the format:vertex1 vertex2 #edges. For example:A   B   2
 B   A   1
 A   C   1Additionaly,MACH2can output files in Graphviz DOT format or JSON format.InputMACH2takes as input two files -Input tree file: Tree file describing the input clone tree.Leaf labeling file: Labeling file describing the leaf labeling of input clone tree.OutputFor each solution,MACH2can output five types of files.Refined tree file: Tree file describing the output refined tree.Vertex labeling file: Labeling file describing the vertex labeling of the refined tree.Refined tree DOT: Refined tree with vertex labeling in DOT format.Migration graph file: Multi-graph file describing the migration graph.Migration graph DOT: Migration graph in DOT format.AdditionalyMACH2can return JSON file encoding all the solutions (refined tree with vertex labeling and migration graph). The JSON file can be directly passed toMACH2-viz. The exact format of the JSON file is describedhere.MACH2also prints<primary location> <number of migrations> <number of comigrations> Optimal <running time (in seconds)>on console.UsageMACH2can be run using python.usage: mach2 [-h] [-p PRIMARY] [-c COLORMAP] [--log] [-o OUTPUT] [-N NSOLUTIONS] [-C] [-t THREADS] [-s] [-S] clone_tree leaf_labeling

            MACH2

            positional arguments:
            clone_tree            Input clone tree
            leaf_labeling         Input leaf labeling

            options:
            -h, --help            show this help message and exit
            -p PRIMARY, --primary PRIMARY
                                    Primary anatomical site
            -c COLORMAP, --colormap COLORMAP
                                    Color map file
            --log                 Outputs Gurobi logging
            -o OUTPUT, --output OUTPUT
                                    Output folder
            -N NSOLUTIONS, --nsolutions NSOLUTIONS
                                    Maximum number of solutions retained
            -C, --count_solutions
                                    Only prints the number of solutions (default=False)
            -t THREADS, --threads THREADS
                                    Number of threads
            -s, --suboptimal      Returns suboptimal solutions without duplicates, may be slow (default=False)
            -S, --seeding_sites   Minimizes the number of seeding sites too (default=False)An example execution$ mach2 data/mcpherson_2016/patient1.tree data/mcpherson_2016/patient1.labeling -c data/mcpherson_2016/coloring.txt