| Name | hwetests JSON |
| Version |
0.9.8
JSON |
| download |
| home_page | https://github.com/ExtraFlash/HWE_tests_package |
| Summary | A python package containing two statistical tests for HWE testing: Gibbs Sampling tests and a modified Chi Squared tests that handles ambiguity |
| upload_time | 2024-08-29 10:13:48 |
| maintainer | None |
| docs_url | None |
| author | Or Shkuri |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<br>
<img src="https://github.com/louzounlab/HWE_Tests/assets/29067588/58bff417-6493-4aaa-a435-3b255b6c0319" width="300"/>
<br>
<p>
<p align="center">
<a href="https://img.shields.io/badge/python-100%25-blue">
<img alt="python" src="https://img.shields.io/badge/python-100%25-blue">
</a>
<a href="https://img.shields.io/badge/license-MIT-blue">
<img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
</a>
The Hardy-Weinberg Equilibrium (HWE) assumption is essential to many population genetics models, which assumes that allele pairs from a given population are random. An HWE test needs to test whether the pairing are random or not.
Our python package contains three statistical tests for HWE testing:
- **ASTA**
- **UMAT**
- **UMAT with uncertainty**
Both **ASTA** and **UMAT with sampling** assume ambiguity in the observations while **UMAT** does not.
## Table of Contents
- [Installation](#installation)
- [Quick tour](#quick_tour)
- [Examples](#examples)
## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install hwetests.
```bash
pip install hwetests
```
## Quick tour
To immediately use our package, you only need to run a single function.<br>
First you have to prepare a csv file which have a different format for the ambiguous and the unambiguous case.
### Ambiguous case
The csv should look like this:
```csv
ID,Allele1,Allele2,Probability
0,2,12,0.1
0,6,7,0.9
1,0,17,1.0
```
- ID: the ID of the individual
- Allele1: the first allele
- Allele2: the second allele
- Probability: the probability of the pair (Allele1, Allele2) to be the true pair for the given ID.
A few notes:
- The csv file is not required to have the column names in the first row.
- The probabilities are not required to sum to 1 for each ID (they are normalized in the code).
- A row that contains the pair (Allele1, Allele2) and another row that contains the pair (Allele2, Allele1) are treated as the same pair.
You can then run ASTA or UMAT with uncertainty using one function:
#### ASTA
```python
def full_algorithm(file_path,
is_first_row_contains_columns_names=False,
cutoff_value=0.0,
should_save_csv=False,
should_save_plot=False,
title=''):
```
Where:
- `file_path`: A path to a csv file with columns: 1) index or id of a donor (integer or string).
Assuming columns are separated with , or + and no whitespaces in the csv file. 2) first allele (integer or string). 3) second allele (integer or string). 4) probability (float).
- `is_first_row_contains_columns_names`: True if the first row in the csv file contains the columns names, False otherwise.
- `cutoff_value`: (optional, default value is 0.0) A float value that decides to not account (O-E)^2 / E in the summation of the Chi-Squared statistic if E < cutoff.
- `should_save_csv`: (optional, default value is False) Either boolean or string, if it's True then a csv with the columns:
`[first allele, second allele, observed, expected, variance]` is saved (named 'alleles_data.csv')
and if it's a string then a csv with the given string name is saved.
- `should_save_plot`: (optional, default value is False) Either boolean or string, if it's True then
an image containing 2 bar plots is saved (named 'alleles_barplot.png') for each allele showing its chi squared statistic over degrees of freedom
(summing over the observations only associated with this allele) and -log_10(p_value). If it's a string and ends with '.pdf' then the plot is saved in pdf format.
Otherwise, it's saved in png format.
If it's a string then a png with the given string name is saved.
- `title`: (optional, default value is '') A string that will be the title of the plot.
Returns: p-value (float), Chi-Squared statistic (float), degrees of freedom (integer)
#### UMAT with uncertainty
```python
def full_algorithm(file_path,
start_from=30000,
iterations=100000,
is_first_row_contains_columns_names=False):
```
Where:
- `file_path`: A path to a csv file with columns: 1) index or id of a donor (integer or string). 2) first allele (integer or string). 3) second allele (integer or string). 4) probability (float).
Assuming columns are separated with , or + and no whitespaces in the csv file.
- `start_from`: The index to start from when calculating the p-value.
- `iterations`: The amount of iterations to perform.
- `is_first_row_contains_columns_names`: If True then it is assumed that the first row contains the
columns names: i.e. 'column1,column2,...'.
Returns: A p-value under the null Hypothesis that observations are distributed around HWE.
### Unambiguous case
The csv should look like this:
```csv
0,2,12
3,6,7
1,0,17
```
Which represents a square matrix where each element a_ij is the number of times the pair (i, j) or (j, i) was observed.<br>
You can then run UMAT with one function:
#### UMAT
```python
def full_algorithm(observations,
start_from=30000,
iterations=100000,
should_save_plot=False):
```
Where:
- `observations`: A numpy square matrix where a_ij is the amount of donors
observed alleles i,j.
- `should_save_plot`: Either boolean or string, if it's True then plot of the perturbations is saved
(named 'umat_plot.png') and if it's a string then a plot with the given string name is saved.
- `start_from`: The index to start from when calculating the p-value.
- `iterations`: The amount of iterations to perform.
Returns: A p-value under the null Hypothesis that observations are distributed around HWE.
## Examples
Here we show how to use our package with simulated data given in our package.
### ASTA test
```python
from HWE_Tests.hwetests import asta
from HWE_Tests.hwetests.tests import dataloader
if __name__ == '__main__':
# getting the absolute path to the 'ambiguous_data.csv' file
ambiguous_data_path = dataloader.get_path(is_ambiguous=True)
# Perform ASTA
p_value, statistic, dof = asta.full_algorithm(file_path=ambiguous_data_path,
cutoff_value=4.0)
print(f'p-value: {p_value}')
print(f'statistic: {statistic}')
print(f'degrees of freedom: {dof}')
```
### UMAT test
```python
from HWE_Tests.hwetests import umat
from HWE_Tests.hwetests.tests import dataloader
import numpy as np
if __name__ == '__main__':
# getting the absolute path to the 'unambiguous_data.csv' file
unambiguous_data_path = dataloader.get_path(is_ambiguous=False)
# import data from csv file as a numpy array
data = np.genfromtxt(unambiguous_data_path, delimiter=',')
# Perform UMAT
p_value = umat.full_algorithm(data)
print(f'p-value: {p_value}')
```
### UMAT with uncertainty test
```python
from HWE_Tests.hwetests import umat_with_uncertainty
from HWE_Tests.hwetests.tests import dataloader
if __name__ == '__main__':
# getting the absolute path to the 'ambiguous_data.csv' file
ambiguous_data_path = dataloader.get_path(is_ambiguous=True)
# Perform UMAT with sampling
p_value = umat_with_uncertainty.full_algorithm(file_path='../data/ambiguous_data.csv')
print(f'p-value: {p_value}')
```
You can find the scripts and the simulated data in:
```bash
├───hwetests
│ ├───tests
│ │ ├───data
│ │ │ └───unambiguous_data.csv # for ASTA and UMAT with sampling (contains 50k population, 20 alleles, 0.2 uncertainty, in HWE)
│ │ │ └───ambiguous_data.csv # for UMAT (contains 100k population, in HWE)
│ │ ├───scripts
│ │ │ └───asta_test.py
│ │ │ └───umat_test.py
│ │ │ └───umat_with_sampling_test.py
│ │ └───dataloader.py
```
MIT License
Copyright (c) 2024 Or Shkuri
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/ExtraFlash/HWE_tests_package",
"name": "hwetests",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Or Shkuri",
"author_email": "orshkuri2000@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3f/cb/15998f4f9fe2713dc5e564293f026b41913e3514ae0954e61545cdf8753a/hwetests-0.9.8.tar.gz",
"platform": null,
"description": "<p align=\"center\">\r\n <br>\r\n <img src=\"https://github.com/louzounlab/HWE_Tests/assets/29067588/58bff417-6493-4aaa-a435-3b255b6c0319\" width=\"300\"/>\r\n <br>\r\n<p>\r\n<p align=\"center\">\r\n <a href=\"https://img.shields.io/badge/python-100%25-blue\">\r\n <img alt=\"python\" src=\"https://img.shields.io/badge/python-100%25-blue\">\r\n </a>\r\n <a href=\"https://img.shields.io/badge/license-MIT-blue\">\r\n <img alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-blue\">\r\n </a>\r\n\r\nThe Hardy-Weinberg Equilibrium (HWE) assumption is essential to many population genetics models, which assumes that allele pairs from a given population are random. An HWE test needs to test whether the pairing are random or not.\r\n\r\nOur python package contains three statistical tests for HWE testing:\r\n- **ASTA**\r\n- **UMAT**\r\n- **UMAT with uncertainty**\r\n\r\nBoth **ASTA** and **UMAT with sampling** assume ambiguity in the observations while **UMAT** does not.\r\n\r\n## Table of Contents\r\n\r\n- [Installation](#installation)\r\n- [Quick tour](#quick_tour)\r\n- [Examples](#examples)\r\n\r\n## Installation\r\nUse the package manager [pip](https://pip.pypa.io/en/stable/) to install hwetests.\r\n```bash\r\npip install hwetests\r\n```\r\n\r\n## Quick tour\r\nTo immediately use our package, you only need to run a single function.<br>\r\nFirst you have to prepare a csv file which have a different format for the ambiguous and the unambiguous case.\r\n### Ambiguous case\r\nThe csv should look like this:\r\n```csv\r\nID,Allele1,Allele2,Probability\r\n0,2,12,0.1\r\n0,6,7,0.9\r\n1,0,17,1.0\r\n```\r\n- ID: the ID of the individual\r\n- Allele1: the first allele\r\n- Allele2: the second allele\r\n- Probability: the probability of the pair (Allele1, Allele2) to be the true pair for the given ID. \r\n\r\nA few notes:\r\n- The csv file is not required to have the column names in the first row.\r\n- The probabilities are not required to sum to 1 for each ID (they are normalized in the code).\r\n- A row that contains the pair (Allele1, Allele2) and another row that contains the pair (Allele2, Allele1) are treated as the same pair.\r\n\r\nYou can then run ASTA or UMAT with uncertainty using one function:\r\n#### ASTA\r\n```python\r\ndef full_algorithm(file_path,\r\n is_first_row_contains_columns_names=False,\r\n cutoff_value=0.0,\r\n should_save_csv=False,\r\n should_save_plot=False,\r\n title=''):\r\n```\r\nWhere:\r\n- `file_path`: A path to a csv file with columns: 1) index or id of a donor (integer or string).\r\n Assuming columns are separated with , or + and no whitespaces in the csv file. 2) first allele (integer or string). 3) second allele (integer or string). 4) probability (float).\r\n- `is_first_row_contains_columns_names`: True if the first row in the csv file contains the columns names, False otherwise.\r\n- `cutoff_value`: (optional, default value is 0.0) A float value that decides to not account (O-E)^2 / E in the summation of the Chi-Squared statistic if E < cutoff.\r\n- `should_save_csv`: (optional, default value is False) Either boolean or string, if it's True then a csv with the columns:\r\n `[first allele, second allele, observed, expected, variance]` is saved (named 'alleles_data.csv')\r\n and if it's a string then a csv with the given string name is saved.\r\n- `should_save_plot`: (optional, default value is False) Either boolean or string, if it's True then\r\n an image containing 2 bar plots is saved (named 'alleles_barplot.png') for each allele showing its chi squared statistic over degrees of freedom\r\n (summing over the observations only associated with this allele) and -log_10(p_value). If it's a string and ends with '.pdf' then the plot is saved in pdf format.\r\n Otherwise, it's saved in png format.\r\n If it's a string then a png with the given string name is saved.\r\n- `title`: (optional, default value is '') A string that will be the title of the plot.\r\n\r\nReturns: p-value (float), Chi-Squared statistic (float), degrees of freedom (integer)\r\n\r\n#### UMAT with uncertainty\r\n```python\r\ndef full_algorithm(file_path,\r\n start_from=30000,\r\n iterations=100000,\r\n is_first_row_contains_columns_names=False):\r\n```\r\nWhere:\r\n- `file_path`: A path to a csv file with columns: 1) index or id of a donor (integer or string). 2) first allele (integer or string). 3) second allele (integer or string). 4) probability (float).\r\nAssuming columns are separated with , or + and no whitespaces in the csv file.\r\n- `start_from`: The index to start from when calculating the p-value.\r\n- `iterations`: The amount of iterations to perform.\r\n- `is_first_row_contains_columns_names`: If True then it is assumed that the first row contains the\r\n columns names: i.e. 'column1,column2,...'.\r\n\r\nReturns: A p-value under the null Hypothesis that observations are distributed around HWE.\r\n\r\n### Unambiguous case\r\nThe csv should look like this:\r\n```csv\r\n0,2,12\r\n3,6,7\r\n1,0,17\r\n```\r\nWhich represents a square matrix where each element a_ij is the number of times the pair (i, j) or (j, i) was observed.<br>\r\nYou can then run UMAT with one function:\r\n#### UMAT\r\n```python\r\ndef full_algorithm(observations,\r\n start_from=30000,\r\n iterations=100000,\r\n should_save_plot=False):\r\n```\r\nWhere:\r\n- `observations`: A numpy square matrix where a_ij is the amount of donors\r\n observed alleles i,j.\r\n- `should_save_plot`: Either boolean or string, if it's True then plot of the perturbations is saved\r\n (named 'umat_plot.png') and if it's a string then a plot with the given string name is saved.\r\n- `start_from`: The index to start from when calculating the p-value.\r\n- `iterations`: The amount of iterations to perform.\r\n\r\nReturns: A p-value under the null Hypothesis that observations are distributed around HWE.\r\n\r\n\r\n## Examples\r\n\r\nHere we show how to use our package with simulated data given in our package.\r\n\r\n### ASTA test\r\n\r\n```python\r\n\r\nfrom HWE_Tests.hwetests import asta\r\nfrom HWE_Tests.hwetests.tests import dataloader\r\n\r\nif __name__ == '__main__':\r\n # getting the absolute path to the 'ambiguous_data.csv' file\r\n ambiguous_data_path = dataloader.get_path(is_ambiguous=True)\r\n # Perform ASTA\r\n p_value, statistic, dof = asta.full_algorithm(file_path=ambiguous_data_path,\r\n cutoff_value=4.0)\r\n print(f'p-value: {p_value}')\r\n print(f'statistic: {statistic}')\r\n print(f'degrees of freedom: {dof}')\r\n```\r\n\r\n### UMAT test\r\n\r\n```python\r\n\r\nfrom HWE_Tests.hwetests import umat\r\nfrom HWE_Tests.hwetests.tests import dataloader\r\nimport numpy as np\r\n\r\nif __name__ == '__main__':\r\n # getting the absolute path to the 'unambiguous_data.csv' file\r\n unambiguous_data_path = dataloader.get_path(is_ambiguous=False)\r\n # import data from csv file as a numpy array\r\n data = np.genfromtxt(unambiguous_data_path, delimiter=',')\r\n # Perform UMAT\r\n p_value = umat.full_algorithm(data)\r\n print(f'p-value: {p_value}')\r\n```\r\n\r\n### UMAT with uncertainty test\r\n\r\n```python\r\n\r\nfrom HWE_Tests.hwetests import umat_with_uncertainty\r\nfrom HWE_Tests.hwetests.tests import dataloader\r\n\r\nif __name__ == '__main__':\r\n # getting the absolute path to the 'ambiguous_data.csv' file\r\n ambiguous_data_path = dataloader.get_path(is_ambiguous=True)\r\n # Perform UMAT with sampling\r\n p_value = umat_with_uncertainty.full_algorithm(file_path='../data/ambiguous_data.csv')\r\n print(f'p-value: {p_value}')\r\n```\r\n\r\nYou can find the scripts and the simulated data in:\r\n```bash\r\n\u251c\u2500\u2500\u2500hwetests\r\n\u2502 \u251c\u2500\u2500\u2500tests\r\n\u2502 \u2502 \u251c\u2500\u2500\u2500data\r\n\u2502 \u2502 \u2502 \u2514\u2500\u2500\u2500unambiguous_data.csv # for ASTA and UMAT with sampling (contains 50k population, 20 alleles, 0.2 uncertainty, in HWE)\r\n\u2502 \u2502 \u2502 \u2514\u2500\u2500\u2500ambiguous_data.csv # for UMAT (contains 100k population, in HWE)\r\n\u2502 \u2502 \u251c\u2500\u2500\u2500scripts\r\n\u2502 \u2502 \u2502 \u2514\u2500\u2500\u2500asta_test.py\r\n\u2502 \u2502 \u2502 \u2514\u2500\u2500\u2500umat_test.py\r\n\u2502 \u2502 \u2502 \u2514\u2500\u2500\u2500umat_with_sampling_test.py\r\n\u2502 \u2502 \u2514\u2500\u2500\u2500dataloader.py\r\n```\r\nMIT License\r\n\r\nCopyright (c) 2024 Or Shkuri\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A python package containing two statistical tests for HWE testing: Gibbs Sampling tests and a modified Chi Squared tests that handles ambiguity",
"version": "0.9.8",
"project_urls": {
"Homepage": "https://github.com/ExtraFlash/HWE_tests_package"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4fc3620de4338ed124b4db1faa5c7ce16f18131ad9ae7f38bc9966e8402f18e",
"md5": "ee2cc178459c60075241fd52f59982ac",
"sha256": "ba7696086f8cac44e15dace4c07bb598808a8d4824d5f836c56c17ef6707c838"
},
"downloads": -1,
"filename": "hwetests-0.9.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee2cc178459c60075241fd52f59982ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 488617,
"upload_time": "2024-08-29T10:13:46",
"upload_time_iso_8601": "2024-08-29T10:13:46.783920Z",
"url": "https://files.pythonhosted.org/packages/f4/fc/3620de4338ed124b4db1faa5c7ce16f18131ad9ae7f38bc9966e8402f18e/hwetests-0.9.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3fcb15998f4f9fe2713dc5e564293f026b41913e3514ae0954e61545cdf8753a",
"md5": "4ca8b616080cbfc22fa59e14582acf69",
"sha256": "540d0cacc504c9bc22a2c9a92080c252852993d69f90633b898f914d85678472"
},
"downloads": -1,
"filename": "hwetests-0.9.8.tar.gz",
"has_sig": false,
"md5_digest": "4ca8b616080cbfc22fa59e14582acf69",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 489579,
"upload_time": "2024-08-29T10:13:48",
"upload_time_iso_8601": "2024-08-29T10:13:48.649356Z",
"url": "https://files.pythonhosted.org/packages/3f/cb/15998f4f9fe2713dc5e564293f026b41913e3514ae0954e61545cdf8753a/hwetests-0.9.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 10:13:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ExtraFlash",
"github_project": "HWE_tests_package",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hwetests"
}
