{
"info": {
"author": "Matthew Marshall",
"author_email": "matthewmarshall124@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 3 - Alpha",
"Environment :: Console",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Topic :: Scientific/Engineering :: Bio-Informatics"
],
"description": "Powerball\n A Tool for Competitive Lottery Analysis of Bacterial Groups
\n by Matthew Marshall and John Darcy
\n\n ---\n\n### What is Competitive Lottery Analysis?\n\nCompetitive Lottery Analysis is examining the competitiveness and \"lottery-ness\" of a number of groups in a specific kind of environment. A competitive lottery environment is one where many species are competing for dominance of a small number of sites or patches. Species in these environments will either dominate a site, forcing all other species out, or will coexist with other species on that patch. Here we define competitiveness as the degree to which a group is consistently dominated by a small number of species within that group, and lottery-ness, which we define as the extent to which the same species will always dominate within a particular group of species. Competitive lottery analysis allows us to explore those metrics by analyzing population data to see which groups of species, are competitive, how competitive they are relative to other species, and how deterministically they dominate their groups.\n\n### What is Powerball?\n\nPowerball is a Python 3 command-line tool that can be used to perform competitive lottery analysis of user-defined groups of species using Monte Carlo Simulation. It was developed for a research project as part of the Colorado Biomedical Informatics Summer Training Fellowship at the University of Colorado Anschutz Medical Campus. The use-cases for PowerBall are varied, and clinically relevant. For example, users can find which bacteria are competing with potential pathogens, and the extent to which that competition regularly occurs. Both the competitiveness and lottery-ness results of this analysis could inform patient outcome predictions as well as potential treatment plans. This knowledge provides valuable medical insight and may help inform the discovery of novel or probiotic treatments and inform treatment decisions for known pathogens. Additionally, PowerBall can be used in an ecological research framework using many different samples to better examine how competitiveness and/or lottery-ness change across environments, across patients, or across time.\n\n### Installation\n\nYou can install Powerball through the Python Package Index (PyPI) by running `pip install powerball`\n\n### Usage\n\nPowerball takes one mandatory argument: the name of an input csv file where each row represents a species and each column represents a sample of population data about that species. The final column of the table is a string used for grouping species based on some user-defined grouping parameter. For example, you could decide that all species that are taxonomically similar belong in the same group. An example of what an input file should look like is given by the table below and in data/example.csv:\n\n\n|Species |Sample A |Sample B |Sample C |Sample D |Sample E| Groups |\n|--- | --- | --- | --- | --- | --- | --- |\n|**Species 1**| 30 | 10 | 30 | 10 | 10 | Group 1|\n|**Species 2**| 15 | 20 | 25 | 11 | 15 | Group 1|\n|**Species 3**| 20 | 5 | 15 | 18 | 0 | Group 1|\n|**Species 4**| 5 | 0 | 10 | 13 | 5 | Group 2|\n|**Species 5**| 10 | 5 | 0 | 14 | 20 | Group 2|\n|**Species 6**| 15 | 30 | 0 | 10 | 20 | Group 2|\n|**Species 7**| 10 | 10 | 20 | 5 | 34 | Group 3|\n|**Species 8**| 5 | 10 | 17 | 0 | 0 | Group 3|\n|**Species 9**| 5 | 17 | 3 | 25 | 20 | Group 3|\n\nPowerball has a minimum group size of 3 (each group must have at least 3 rows). Any groups below that minimum will be ignored. A warning will be displayed if any groups are ignored, and the names of the groups will be shown. This minimum group size can be changed through the command line argument `-gs` or `--groupSize` by specifying a number after it.\n\n
\n\nBasic usage for Powerball is `python powerball.py filename.csv` This is run from the root directory of the project and filename.csv can be renamed to anything as long as it ends in .csv\n\nThis will show the competitiveness score, lottery score, and p-values for all groups, all rounded to 4 decimal places. See the image below for an example:\n\n\n\n\nThis data is also saved to an output csv file (default name is Output.csv)\n\n
\nFor more advanced usage, Powerball has many different command line arguments. A full list can be shown by running `python powerball.py --help` or `python powerball.py -h`\n\n\n\n\nPowerball automatically generates an interactive graph of the output data using Bokeh (this can be silenced using the --chartStyle argument with a value greater than 3)\n\n## How Does it Work?\n\nThe input data specified in the csv file is used to generate a list of **Shannon Diversity** scores for each group. Shannon Diversity \tdiversity is a statistical measure of the diversity of a community given by the formula:\n\n\n\nwhere pi is the proportion of individuals belonging to the ith species in the group and R is the richness or number of species within a group.\n\nThe diversity scores for a group are then compared against a null distribution of scores generated through **Permutational Monte Carlo simulation**.\n\nThe scores within the null distribution are diversity scores for a random group of the same size created by permuting all rows (including species not within the group of interest) of the input matrix.\n\nThis process is repeated until a sufficiently large distribution is generated for each group (number of simulations is controlled by the `--nullSize` argument, with a default value of 1000)\n\nObserving diversity scores which are higher than expected by the null hypothesis would imply relatively even population distribution between the species of a group. This would also imply that more competition exists within that group. We define competitiveness as the **Standardized Effect Size** of the group, given by the formula:\n\n\n\n\n\nwhere \u00ce\u00bc1 is the mean for our empirical Shannon Diversity data, \u00ce\u00bc2 is the mean for the null distribution, and \u00cf\u0192 is the standard deviation based on the null distribution. \n\n\n**Lottery scores**, which represent how deterministically a species dominates its group, are also generated through Permutational Monte Carlo simulation, with two key differences:\n\n1. Instead of generating diversity scores by permuting the rows of the input matrix, we permute the columns within each group. \n\n2. Diversity scores are taken from row sums instead of the entire row.\n\nCompetitiveness scores and lottery scores both have **1-tailed P-values**, calculated permutationally as the proportion of values in the null distribution more extreme than the observed value.\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/mmarshall124/powerball",
"keywords": "",
"license": "MIT",
"maintainer": "",
"maintainer_email": "",
"name": "powerball",
"package_url": "https://pypi.org/project/powerball/",
"platform": "",
"project_url": "https://pypi.org/project/powerball/",
"project_urls": {
"Homepage": "https://github.com/mmarshall124/powerball"
},
"release_url": "https://pypi.org/project/powerball/0.2.1/",
"requires_dist": null,
"requires_python": "",
"summary": "A tool for competitive lottery analysis of bacterial groups.",
"version": "0.2.1"
},
"last_serial": 5887689,
"releases": {
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "7aa1a24290dd8b17be7e1e7928520301",
"sha256": "3351879c9c0afc9b5ded71ba177b51868e8a74bacaedd0c4143b5bf0e38d2d94"
},
"downloads": -1,
"filename": "powerball-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7aa1a24290dd8b17be7e1e7928520301",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12332,
"upload_time": "2019-08-20T00:31:18",
"url": "https://files.pythonhosted.org/packages/b0/57/e7389bd3c4b660df6d356144a72584ad6d3d90074878a8a1b4d1558c5190/powerball-0.1.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "f951aa551d7dbe2e674e0f1220f67e16",
"sha256": "fb97af751fcb647e797b837aed843057193d1630848cbd565ca4f70de88771e6"
},
"downloads": -1,
"filename": "powerball-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f951aa551d7dbe2e674e0f1220f67e16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8686,
"upload_time": "2019-08-20T00:31:22",
"url": "https://files.pythonhosted.org/packages/0b/b7/b149c69280d952716c0b6a26b35eaec6dd3d6fd022717b0dbacd4a13c109/powerball-0.1.0.tar.gz"
}
],
"0.2.0": [
{
"comment_text": "",
"digests": {
"md5": "51556f317a8c6e3c008486b6919c9639",
"sha256": "694af2c0ebbcd3b3e8b3ab1689684641e5a49202fe6b5c30d96b6382461b741c"
},
"downloads": -1,
"filename": "powerball-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "51556f317a8c6e3c008486b6919c9639",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2639,
"upload_time": "2019-09-04T16:23:38",
"url": "https://files.pythonhosted.org/packages/87/80/30e3de534a2135b68c3d5f4eb5e689ee8f8880ad98bbd9e4d80188454091/powerball-0.2.0.tar.gz"
}
],
"0.2.1": [
{
"comment_text": "",
"digests": {
"md5": "d54063fa737ffc8ee09b1cc550d4156d",
"sha256": "55a3603ff83b9bfd7f0f51074f21d990a51648ed22ba191864beefc0d9e64291"
},
"downloads": -1,
"filename": "powerball-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d54063fa737ffc8ee09b1cc550d4156d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12441,
"upload_time": "2019-09-26T00:02:17",
"url": "https://files.pythonhosted.org/packages/c0/6a/ad96659a61fc370cb4a984b45766b5f2152e46713fb063565048b702e55f/powerball-0.2.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5cb27d9b94b9f1ab24ca016e26bbe2f6",
"sha256": "ec9642d782a6ec7cc5f09eeeab645889a73bf02d5eff70c10325a10e5b02a5de"
},
"downloads": -1,
"filename": "powerball-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "5cb27d9b94b9f1ab24ca016e26bbe2f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9826,
"upload_time": "2019-09-26T00:02:20",
"url": "https://files.pythonhosted.org/packages/0b/6c/84076f99f7f948aaee2811691b9c912c49afcb2c8670cdb72fd5939fe870/powerball-0.2.1.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d54063fa737ffc8ee09b1cc550d4156d",
"sha256": "55a3603ff83b9bfd7f0f51074f21d990a51648ed22ba191864beefc0d9e64291"
},
"downloads": -1,
"filename": "powerball-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d54063fa737ffc8ee09b1cc550d4156d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12441,
"upload_time": "2019-09-26T00:02:17",
"url": "https://files.pythonhosted.org/packages/c0/6a/ad96659a61fc370cb4a984b45766b5f2152e46713fb063565048b702e55f/powerball-0.2.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5cb27d9b94b9f1ab24ca016e26bbe2f6",
"sha256": "ec9642d782a6ec7cc5f09eeeab645889a73bf02d5eff70c10325a10e5b02a5de"
},
"downloads": -1,
"filename": "powerball-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "5cb27d9b94b9f1ab24ca016e26bbe2f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9826,
"upload_time": "2019-09-26T00:02:20",
"url": "https://files.pythonhosted.org/packages/0b/6c/84076f99f7f948aaee2811691b9c912c49afcb2c8670cdb72fd5939fe870/powerball-0.2.1.tar.gz"
}
]
}