| Name | mach2 JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Migration Analysis of Clonal History 2 |
| upload_time | 2025-02-25 16:39:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | BSD 3-Clause License
Copyright (c) 2024, Mrinmoy Saha Roddur, Vikram Ramavarapu, Abigail Bunkum,
Ariana Huebner, Roman Minyev, Nicholas McGranahan, Simone Zaccaria, Mohammed El-Kebir
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
computational biology
bioinformatics
cancer
metastasis
phylogeny
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MACH2
A mathematical framework for inferring migration histories of metastatic cancer from clone phylogeny and the location of extant clones.
## Table of contents
1. [Installation](#installation)
- [Prerequisite](#prerequisite)
- [Install using `pip`](#install-using-pip)
2. [Usage instruction](#usage-instruction)
- [From `JupyterLab`](#from-jupyterlab)
- [From Command Line](#from-command-line)
<!-- - [I/O formats](#i-o-formats)
- [Usage](#usage) -->
## 1. Installation
### Prerequisites
- **Python** - `MACH2` requires Python 3.7 or newer.
- **ILP solver** - `MACH2` requires an ILP solver installed to solve **PMH-TR**. Currently `MACH2` only supports `Gurobi optimizer`, but we are going to add support for more ILP solvers in the future. `MACH2` requires a valid Gurobi installation and license key. The location of Gurobi should be present in `LD_LIBRARY_PATH` (linux) or `DYLD_LIBRARY_PATH` (macOS) the license key should be saved in the environment variable `GRB_LICENSE_KEY`.
<!-- ### Install using `pip`
`MACH2` can easily be installed using `pip`, the package installer for Python. Open a terminal or command prompt and run the following command:
$ pip install mach2
If you want to use `MACH2` with `JupyterLab`, you'll need additional dependencies. To install these optional dependencies, you can run the following command:
$ pip install mach2[jupyter]
PyPI version is currently broken. We'll update it ASAP.-->
### Install using `conda`
`MACH2` can be installed using `conda`. We advise to create a new environment in `conda`. If creating a new environment, dependencies can be installed simultaneously.
$ conda create -n mach2 python=3 pandas networkx gurobi jupyterlab graphviz pygraphviz -c conda-forge -c gurobi
$ conda activate mach2
If using existing conda environment, the following command installs the dependencies.
$ conda install -c conda-forge -c gurobi pandas networkx gurobi jupyterlab graphviz pygraphviz
Next, we install `MACH2`. To that end, we download `MACH2` repository from GitHub and install it.
$ git clone https://github.com/elkebir-group/MACH2.git
$ cd MACH2
$ pip install . --no-deps
## Usage Instruction
### I/O formats
We describe various formats used by `MACH2`.
1. **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: `node1 node2`. For example:
1 2
2 3
2 4
3 5
2. **Tree file with timing/comigrations** : Tree file with timestamps. Edges with the same timestamp belong to the same comigration, and a timestamp with `-1` represents non-migration. Each line corresponds to an edge in the format: `node1 node2 timestamp`. For example:
1 2 -1
2 3 1
2 4 1
3 5 2
3. **Observed labeling file** : The observed labeling file contains zero or more location labels assigned to each node of the input clonal tree. Each line in the file corresponds to a node and the labels assigned to it in the format: `node label1 label2 ...`. If a node is not observed anywhere, it may be skipped. For example:
1 A B
3 B
4 A C
5 C
4. **Location labeling file** : The location labeling file contains the unique location label of origin assigned to each node. Each line in the file corresponds to a node and the location label of origin are in the format: `node label`. For example:
1 A
2 B
3 C
5. **Node of origin file** : The node of origin file maps the nodes of the refined tree to the nodes of the input tree. 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 C
Additionaly, `MACH2` can output files in Graphviz DOT format or JSON format.
### Usage
`MACH2` takes as input two files -
1. **Tree file** : Tree file describing the input clone tree.
2. **Observed labeling file** : Labeling file describing the observed labeling of input clone tree.
`MACH2` Can be run using command line, or can be directly accessed from `JupyterLab`.
#### From JupyterLab
The following code snippet imports `MACH2`, runs it for input tree file `input.tree` and input observed labeling file `input.observed.labeling`, and saves the solutions to a variable `solutions`.
import mach2
tree = mach2.MultiLabeledTree.from_files('input.tree', 'input.observed.labeling')
solutions = mach2.MACH2(tree, primary_location='primary', criteria_ordering='UMC').solve()
print(len(solutions))
solutions.summary()
`solutions` is a `SolutionSet` object that behaves as a set. `print(len(solutions))` prints the number of retrived solutions.
The last line draws the summary graph for `solutions.
It is possible to inspect individual solutions too.
solution1 = [sol for sol in solutions][0]
solution1.draw()
solution1.migration_graph().draw()
The second line draws the tree with node labeling, and the third line draws the corresponding migration graph.
For more details, check the documentation for each function.
#### From Terminal
For each solution, `MACH2` can output three types of files.
1. **Tree file with timing/comigrations** : Refined tree file with timestamps/comigrations.
2. **Location labeling file** : Location labeling file describing the location labeling of the refined tree.
3. **Node of origin file** : Node of origin file mapping refined tree nodes to input tree nodes.
Additionaly `MACH2` can return JSON file encoding all the solutions. The JSON file can be directly passed to [MACH2-viz](https://github.com/elkebir-group/mach2-viz). The exact format of the JSON file is described [here](https://github.com/elkebir-group/mach2-viz/README.md).
`MACH2` also prints `<primary location> <number of migrations> <number of comigrations> Optimal <running time (in seconds)>` on console.
`MACH2` can be run using python.
usage: mach2 [-h] [-c CRITERIA] [-s] [-p PRIMARY] [--colormap COLORMAP] [--log] [-o OUTPUT] [--max_solutions MAX_SOLUTIONS] [-t THREADS] [--viz]
clonal_tree observed_labeling
MACH2
positional arguments:
clonal_tree Input clonal tree
observed_labeling Input observed labeling
optional arguments:
-h, --help show this help message and exit
-c CRITERIA, --criteria CRITERIA
Criteria ordering
-s, --seeding_locations
Prioritize solutions with the least number of seeding locations (default=False)
-p PRIMARY, --primary PRIMARY
Primary anatomical location
--colormap COLORMAP Color map file
--log Outputs Gurobi logging (default=False)
-o OUTPUT, --output OUTPUT
Output folder (default=current folder)
--max_solutions MAX_SOLUTIONS
Maximum number of solutions retained (default=37888)
-t THREADS, --threads THREADS
Number of threads
--viz, --open_in_viz Open the locations on MACH2-viz (default=False)
An example execution
$ mach2 data/ovarian/patient2.tree data/ovarian/patient2.observed.labeling --colormap data/ovarian/coloring.txt
Raw data
{
"_id": null,
"home_page": null,
"name": "mach2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Mrinmoy Saha Roddur <mroddur2@illinois.edu>",
"keywords": "Computational biology, Bioinformatics, Cancer, Metastasis, Phylogeny",
"author": null,
"author_email": "Mrinmoy Saha Roddur <mroddur2@illinois.edu>, Vikram Ramavarapu <vikramr2@illinois.edu>, Abigail Bunkum <abigail.bunkum.21@ucl.ac.uk>, \"Ariana Huebner,\" <ariana.huebner.16@ucl.ac.uk>, Roman Minyev <mineyev2@illinois.edu>, \"Nicholas McGranahan,\" <nicholas.mcgranahan.10@ucl.ac.uk>, \"Simone Zaccaria,\" <s.zaccaria@ucl.ac.uk>, Mohammed El-Kebir <melkebir@illinois.edu>",
"download_url": "https://files.pythonhosted.org/packages/63/18/c73103e02a02a2f463f2ab9b88b8512d16eacfcdfbe5da46a4e0a4ae637b/mach2-1.0.0.tar.gz",
"platform": null,
"description": "# MACH2\n\nA mathematical framework for inferring migration histories of metastatic cancer from clone phylogeny and the location of extant clones.\n\n## Table of contents\n\n1. [Installation](#installation) \n - [Prerequisite](#prerequisite) \n - [Install using `pip`](#install-using-pip)\n2. [Usage instruction](#usage-instruction) \n - [From `JupyterLab`](#from-jupyterlab) \n - [From Command Line](#from-command-line) \n <!-- - [I/O formats](#i-o-formats) \n - [Usage](#usage) -->\n\n## 1. Installation\n\n### Prerequisites\n\n- **Python** - `MACH2` requires Python 3.7 or newer.\n- **ILP solver** - `MACH2` requires an ILP solver installed to solve **PMH-TR**. Currently `MACH2` only supports `Gurobi optimizer`, but we are going to add support for more ILP solvers in the future. `MACH2` requires a valid Gurobi installation and license key. The location of Gurobi should be present in `LD_LIBRARY_PATH` (linux) or `DYLD_LIBRARY_PATH` (macOS) the license key should be saved in the environment variable `GRB_LICENSE_KEY`.\n\n<!-- ### Install using `pip`\n\n`MACH2` can easily be installed using `pip`, the package installer for Python. Open a terminal or command prompt and run the following command:\n\n $ pip install mach2\n\nIf you want to use `MACH2` with `JupyterLab`, you'll need additional dependencies. To install these optional dependencies, you can run the following command:\n\n $ pip install mach2[jupyter] \n\nPyPI version is currently broken. We'll update it ASAP.-->\n\n### Install using `conda`\n\n`MACH2` can be installed using `conda`. We advise to create a new environment in `conda`. If creating a new environment, dependencies can be installed simultaneously.\n\n $ conda create -n mach2 python=3 pandas networkx gurobi jupyterlab graphviz pygraphviz -c conda-forge -c gurobi\n $ conda activate mach2\n\nIf using existing conda environment, the following command installs the dependencies.\n\n $ conda install -c conda-forge -c gurobi pandas networkx gurobi jupyterlab graphviz pygraphviz\n\nNext, we install `MACH2`. To that end, we download `MACH2` repository from GitHub and install it.\n\n $ git clone https://github.com/elkebir-group/MACH2.git\n $ cd MACH2\n $ pip install . --no-deps\n\n## Usage Instruction\n\n### I/O formats\n\nWe describe various formats used by `MACH2`.\n\n1. **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: `node1 node2`. For example:\n\n 1 2\n 2 3\n 2 4 \n 3 5\n\n2. **Tree file with timing/comigrations** : Tree file with timestamps. Edges with the same timestamp belong to the same comigration, and a timestamp with `-1` represents non-migration. Each line corresponds to an edge in the format: `node1 node2 timestamp`. For example:\n\n 1 2 -1\n 2 3 1\n 2 4 1\n 3 5 2\n\n3. **Observed labeling file** : The observed labeling file contains zero or more location labels assigned to each node of the input clonal tree. Each line in the file corresponds to a node and the labels assigned to it in the format: `node label1 label2 ...`. If a node is not observed anywhere, it may be skipped. For example:\n\n 1 A B\n 3 B\n 4 A C\n 5 C\n\n4. **Location labeling file** : The location labeling file contains the unique location label of origin assigned to each node. Each line in the file corresponds to a node and the location label of origin are in the format: `node label`. For example:\n\n 1 A\n 2 B\n 3 C\n\n5. **Node of origin file** : The node of origin file maps the nodes of the refined tree to the nodes of the input tree. Each line in the file corresponds to a vertex and the labels are in the format: `leaf label`. For example:\n\n 1 A\n 2 B\n 3 C\n \nAdditionaly, `MACH2` can output files in Graphviz DOT format or JSON format.\n\n### Usage\n\n`MACH2` takes as input two files - \n\n1. **Tree file** : Tree file describing the input clone tree.\n2. **Observed labeling file** : Labeling file describing the observed labeling of input clone tree.\n\n\n`MACH2` Can be run using command line, or can be directly accessed from `JupyterLab`.\n\n#### From JupyterLab\n\nThe following code snippet imports `MACH2`, runs it for input tree file `input.tree` and input observed labeling file `input.observed.labeling`, and saves the solutions to a variable `solutions`.\n\n\n import mach2\n tree = mach2.MultiLabeledTree.from_files('input.tree', 'input.observed.labeling')\n solutions = mach2.MACH2(tree, primary_location='primary', criteria_ordering='UMC').solve()\n print(len(solutions))\n solutions.summary()\n\n\n`solutions` is a `SolutionSet` object that behaves as a set. `print(len(solutions))` prints the number of retrived solutions.\nThe last line draws the summary graph for `solutions.\nIt is possible to inspect individual solutions too.\n\n\n solution1 = [sol for sol in solutions][0]\n solution1.draw()\n solution1.migration_graph().draw()\n\nThe second line draws the tree with node labeling, and the third line draws the corresponding migration graph.\nFor more details, check the documentation for each function.\n\n\n#### From Terminal\n\n\nFor each solution, `MACH2` can output three types of files.\n\n1. **Tree file with timing/comigrations** : Refined tree file with timestamps/comigrations.\n2. **Location labeling file** : Location labeling file describing the location labeling of the refined tree.\n3. **Node of origin file** : Node of origin file mapping refined tree nodes to input tree nodes.\n\nAdditionaly `MACH2` can return JSON file encoding all the solutions. The JSON file can be directly passed to [MACH2-viz](https://github.com/elkebir-group/mach2-viz). The exact format of the JSON file is described [here](https://github.com/elkebir-group/mach2-viz/README.md).\n\n`MACH2` also prints `<primary location> <number of migrations> <number of comigrations> Optimal <running time (in seconds)>` on console.\n\n`MACH2` can be run using python.\n\n usage: mach2 [-h] [-c CRITERIA] [-s] [-p PRIMARY] [--colormap COLORMAP] [--log] [-o OUTPUT] [--max_solutions MAX_SOLUTIONS] [-t THREADS] [--viz]\n clonal_tree observed_labeling\n\n MACH2\n\n positional arguments:\n clonal_tree Input clonal tree\n observed_labeling Input observed labeling\n\n optional arguments:\n -h, --help show this help message and exit\n -c CRITERIA, --criteria CRITERIA\n Criteria ordering\n -s, --seeding_locations\n Prioritize solutions with the least number of seeding locations (default=False)\n -p PRIMARY, --primary PRIMARY\n Primary anatomical location\n --colormap COLORMAP Color map file\n --log Outputs Gurobi logging (default=False)\n -o OUTPUT, --output OUTPUT\n Output folder (default=current folder)\n --max_solutions MAX_SOLUTIONS\n Maximum number of solutions retained (default=37888)\n -t THREADS, --threads THREADS\n Number of threads\n --viz, --open_in_viz Open the locations on MACH2-viz (default=False) \n\nAn example execution\n\n $ mach2 data/ovarian/patient2.tree data/ovarian/patient2.observed.labeling --colormap data/ovarian/coloring.txt\n \n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License\n \n Copyright (c) 2024, Mrinmoy Saha Roddur, Vikram Ramavarapu, Abigail Bunkum, \n Ariana Huebner, Roman Minyev, Nicholas McGranahan, Simone Zaccaria, Mohammed El-Kebir\n All rights reserved.\n \n Redistribution and use in source and binary forms, with or without\n modification, are permitted provided that the following conditions are met:\n \n 1. Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n \n 2. Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n \n 3. Neither the name of the copyright holder nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n \n THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\n FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\n SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\n CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\n OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "Migration Analysis of Clonal History 2",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/elkebir-group/MACH2/issues",
"Homepage": "https://github.com/elkebir-group/MACH2",
"Preprint": "https://www.biorxiv.org/content/10.1101/2024.11.19.624301v2"
},
"split_keywords": [
"computational biology",
" bioinformatics",
" cancer",
" metastasis",
" phylogeny"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9df31c3b060212855eca3ec6b7fb5d1f421e84cb344a5a5aec756da49b749e4c",
"md5": "356bd54a2ce5d14ee63a5621c6ec3e1d",
"sha256": "a5c50081230e3712fbd92478b1bed8ed0702e204beaae2336e7b2b20a09b5107"
},
"downloads": -1,
"filename": "mach2-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "356bd54a2ce5d14ee63a5621c6ec3e1d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16816,
"upload_time": "2025-02-25T16:39:50",
"upload_time_iso_8601": "2025-02-25T16:39:50.523051Z",
"url": "https://files.pythonhosted.org/packages/9d/f3/1c3b060212855eca3ec6b7fb5d1f421e84cb344a5a5aec756da49b749e4c/mach2-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6318c73103e02a02a2f463f2ab9b88b8512d16eacfcdfbe5da46a4e0a4ae637b",
"md5": "e145cbfa2772cc8a8a51bb7e4e5b4827",
"sha256": "af2a6774854d5a0b3de91a5c6f6ae85436bf896fd9736023e480884925cd5a32"
},
"downloads": -1,
"filename": "mach2-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e145cbfa2772cc8a8a51bb7e4e5b4827",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16998,
"upload_time": "2025-02-25T16:39:53",
"upload_time_iso_8601": "2025-02-25T16:39:53.227583Z",
"url": "https://files.pythonhosted.org/packages/63/18/c73103e02a02a2f463f2ab9b88b8512d16eacfcdfbe5da46a4e0a4ae637b/mach2-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-25 16:39:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elkebir-group",
"github_project": "MACH2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mach2"
}
