| Name | mach2 JSON |
| Version |
0.0.3
JSON |
| download |
| home_page | |
| Summary | Migration Analysis of Clonal History 2 |
| upload_time | 2023-05-26 03:08:32 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | BSD 3-Clause License Copyright (c) 2022, Mrinmoy Saha Roddur, Vikram Ramavarapu, 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)
- [I/O formats](#i-o-formats)
- [Input](#input)
- [Output](#output)
- [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) and `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]
## 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: `vertex1 vertex2`. For example:
1 2
2 3
2 4
1 3
2. **Labeling 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 C
1. **Multi-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 vertices __vertex1__ and __vertex2__ in the format: `vertex1 vertex2 #edges`. For example:
A B 2
B A 1
A C 1
Additionaly, `MACH2` can output files in Graphviz DOT format or JSON format.
### Input
`MACH2` takes as input two files -
1. **Input tree file** : Tree file describing the input clone tree.
2. **Leaf labeling file** : Labeling file describing the leaf labeling of input clone tree.
### Output
For each solution, `MACH2` can output five types of files.
1. **Refined tree file** : Tree file describing the output refined tree.
2. **Vertex labeling file** : Labeling file describing the vertex labeling of the refined tree.
3. **Refined tree DOT** : Refined tree with vertex labeling in DOT format.
4. **Migration graph file** : Multi-graph file describing the migration graph.
5. **Migration graph DOT** : Migration graph in DOT format.
Additionaly `MACH2` can return JSON file encoding all the solutions (refined tree with vertex labeling and migration graph). 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.
### Usage
`MACH2` can 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
Raw data
{
"_id": null,
"home_page": "",
"name": "mach2",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Computational biology Bioinformatics Cancer Metastasis Phylogeny",
"author": "",
"author_email": "Mrinmoy Saha Roddur <mroddur2@illinois.edu>",
"download_url": "https://files.pythonhosted.org/packages/78/10/fe0da7355aa03a1c5773ea35d1948b2c5ab9d37ed6645019d0b220ac2674/mach2-0.0.3.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 - [I/O formats](#i-o-formats) \n - [Input](#input) \n - [Output](#output) \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) and `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\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: `vertex1 vertex2`. For example:\n\n 1 2\n 2 3\n 2 4 \n 1 3\n\n2. **Labeling 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:\n\n 1 A\n 2 B\n 3 C\n\n1. **Multi-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 vertices __vertex1__ and __vertex2__ in the format: `vertex1 vertex2 #edges`. For example:\n\n A B 2\n B A 1\n A C 1\n\nAdditionaly, `MACH2` can output files in Graphviz DOT format or JSON format.\n\n### Input\n\n`MACH2` takes as input two files - \n\n1. **Input tree file** : Tree file describing the input clone tree.\n2. **Leaf labeling file** : Labeling file describing the leaf labeling of input clone tree.\n\n### Output\n\nFor each solution, `MACH2` can output five types of files.\n\n1. **Refined tree file** : Tree file describing the output refined tree. \n2. **Vertex labeling file** : Labeling file describing the vertex labeling of the refined tree.\n3. **Refined tree DOT** : Refined tree with vertex labeling in DOT format.\n4. **Migration graph file** : Multi-graph file describing the migration graph.\n5. **Migration graph DOT** : Migration graph in DOT format.\n\nAdditionaly `MACH2` can return JSON file encoding all the solutions (refined tree with vertex labeling and migration graph). 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### Usage\n\n`MACH2` can be run using python.\n\n usage: mach2 [-h] [-p PRIMARY] [-c COLORMAP] [--log] [-o OUTPUT] [-N NSOLUTIONS] [-C] [-t THREADS] [-s] [-S] clone_tree leaf_labeling\n\n MACH2\n\n positional arguments:\n clone_tree Input clone tree\n leaf_labeling Input leaf labeling\n\n options:\n -h, --help show this help message and exit\n -p PRIMARY, --primary PRIMARY\n Primary anatomical site\n -c COLORMAP, --colormap COLORMAP\n Color map file\n --log Outputs Gurobi logging\n -o OUTPUT, --output OUTPUT\n Output folder\n -N NSOLUTIONS, --nsolutions NSOLUTIONS\n Maximum number of solutions retained\n -C, --count_solutions\n Only prints the number of solutions (default=False)\n -t THREADS, --threads THREADS\n Number of threads\n -s, --suboptimal Returns suboptimal solutions without duplicates, may be slow (default=False)\n -S, --seeding_sites Minimizes the number of seeding sites too (default=False)\n\nAn example execution\n\n $ mach2 data/mcpherson_2016/patient1.tree data/mcpherson_2016/patient1.labeling -c data/mcpherson_2016/coloring.txt\n \n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2022, Mrinmoy Saha Roddur, Vikram Ramavarapu, 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.",
"summary": "Migration Analysis of Clonal History 2",
"version": "0.0.3",
"project_urls": {
"Bug tracker": "https://github.com/elkebir-group/MACH2/issues",
"Homepage": "https://github.com/elkebir-group/MACH2"
},
"split_keywords": [
"computational",
"biology",
"bioinformatics",
"cancer",
"metastasis",
"phylogeny"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae927aa1922ac4e41be1d4fb035f032fbab8568d07cc1e6d7bba4edf1ad5d451",
"md5": "ffd8c9e98bc95fadfe9b9c7498ef154b",
"sha256": "d5ae35fe725c2a18acb95cd8bc4ac404b1ad31f6c7ca5c29f684d540b5210ece"
},
"downloads": -1,
"filename": "mach2-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffd8c9e98bc95fadfe9b9c7498ef154b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15907,
"upload_time": "2023-05-26T03:08:31",
"upload_time_iso_8601": "2023-05-26T03:08:31.310209Z",
"url": "https://files.pythonhosted.org/packages/ae/92/7aa1922ac4e41be1d4fb035f032fbab8568d07cc1e6d7bba4edf1ad5d451/mach2-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7810fe0da7355aa03a1c5773ea35d1948b2c5ab9d37ed6645019d0b220ac2674",
"md5": "6342452a6095da3121324478997f8c53",
"sha256": "27a55bb4bfcab53d6fed7b68577b6fd292b8a29a7f4d17144d470bd16585ff31"
},
"downloads": -1,
"filename": "mach2-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6342452a6095da3121324478997f8c53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15425,
"upload_time": "2023-05-26T03:08:32",
"upload_time_iso_8601": "2023-05-26T03:08:32.911823Z",
"url": "https://files.pythonhosted.org/packages/78/10/fe0da7355aa03a1c5773ea35d1948b2c5ab9d37ed6645019d0b220ac2674/mach2-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-26 03:08:32",
"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"
}
