# Associations Beyond Chance (ABC)
The ABC model provides a **Bayesian framework to infer multimorbidity associations between health conditions** from Electronic Health Records. The outputs are posterior distribution over pairwise association values, which can be assembled and visualised as multimorbidity weigthed network.
The ABC model was presented on the article [*"Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups"*](https://authors.elsevier.com/sd/article/S2352396424001166). This repository also provides code to reproduce the experiments and visualisations there. If you use this code, please cite the paper:
> Romero Moreno G., Restocchi V., Fleuriot JD., Anand A., Mercer SW., Guthrie B. (2024). [*Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups*](https://www.sciencedirect.com/science/article/pii/S2352396424001166); **eBioMedicine**, Volume 102, 105081, ISSN 2352-3964, https://doi.org/10.1016/j.ebiom.2024.105081.
```
@article{ROMEROMORENO2024105081,
title = {Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups},
journal = {eBioMedicine},
volume = {102},
pages = {105081},
year = {2024},
issn = {2352-3964},
doi = {https://doi.org/10.1016/j.ebiom.2024.105081},
url = {https://www.sciencedirect.com/science/article/pii/S2352396424001166},
author = {Guillermo {Romero Moreno} and Valerio Restocchi and Jacques D. Fleuriot and Atul Anand and Stewart W. Mercer and Bruce Guthrie},
}
```
## Installation and dependencies
You can install and use the package just by running `python setup.py install`. (It is recommended to perform the installation in a python virtual environment.)
Or alternatively:
- Install [Anaconda](https://docs.anaconda.com/) (if not already installed)
- Execute `conda env create -n ABC --file packages.yml`* in a terminal for creating an environment called `ABC` with all the required packages. *Be aware that it may take a few GB of space.*
- Activate the environment with `conda activate ABC`, and run the code or set up a jupyter notebook server (by running `jupyter notebook`)
> .* Or you can directly execute `conda create -n ABC -c conda-forge numpy=1.22.3 scipy=1.8.0 pandas=1.4.2 matplotlib=3.5.1 seaborn=0.13.1 networkx=2.8 bokeh=3.3.0 cmdstanpy=1.1.0 jupyter`.
While the code is in *python*, Bayesian inference is performed via [Stan](http://mc-stan.org) through the package `cmdstanpy` (version 1.1.0), providing a python API to the *Stan* library. The model (defined in the file [`ABC/models/MLTC_atomic_hyp_mult.stan`](ABC/models/MLTC_atomic_hyp_mult.stan)) could also work with [any stan interface](https://mc-stan.org/users/interfaces/index.html).
## Using the model
Our model can be used simply by running `ABC "path/to/dataset_file.csv"`, which will fit the model and generate output files with the results. For more information on additional argumnets, run `ABC --help`.
Additionally, you can integrate our model into other *python* code directly. You can see an example snippet on how to do so below.
```python
from ABC.model import ABCModel
from ucimlrepo import fetch_ucirepo
# This loads an example dataset. Swap these lines for those loading your dataset
dataset = fetch_ucirepo(name='CDC Diabetes Health Indicators')
data = pd.concat([dataset.data.features, dataset.data.targets ], axis=1)
bin_vars = dataset.variables[dataset.variables["type"] == "Binary"]["name"].to_list()
# Make sure to use columns with binary variables only
model = ABCModel()
model.load_fit(data, "choose_name_for_model", column_names=bin_vars, num_warmup=500, num_samples=2000, random_seed=1)
ABC = model.get_associations() # This retrieves the whole distribution for all association pairs
results = model.get_results_dataframe(credible_inteval_pvalue=0.01) # This creates a table with summary statistics
```
A detailed example with **step-by-step intructions** on how to use the model and produce outputs and visualisations within python code can be found at the tutorial notebook ['ABC_to_ABC.ipynb'](notebooks/ABC_to_ABC.ipynb).
## Reproducing results
You can replicate the results and figures from the [*"Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups"*](https://authors.elsevier.com/sd/article/S2352396424001166) article by running the notebook [`notebooks/results.ipynb`](notebooks/results.ipynb). However, note that this will only be possible if you have access to the dataset used in the study.
You can still reproduce the results shown in that notebook on a different dataset, for which you will need to adapt all functions and variables within the file [`ABC/data.py`](ABC/data.py) to your dataset characteristics and then rerun [`notebooks/results.ipynb`](notebooks/results.ipynb) --- or use the functions in the file [`ABC/results.py`](ABC/results.py).
## Repository structure
* [`ABC/`](ABC/): python files with the basic classes and functions.
* [`ABC/models/`](ABC/models/): files defining *Stan* models.
* [`ABC/output/`](ABC/output/): folder in which to save the fitted models.
* [`notebooks/`](notebooks/): results and examples implementing our models and code.
* [`figs/`](figs/): folder in which to save the figures produced in the notebooks.
## Acknowledgements
Functions and notebooks were inspired by [this repository](https://github.com/jg-you/plant-pollinator-inference/tree/master).
### Contact
Any question, comment, or feedback, contact <Guillermo.RomeroMoreno@ed.ac.uk>, or submit an Issues on GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/Juillermo/ABC.git",
"name": "abc-network",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Bayesian, Multimorbidity",
"author": "Guillermo Romero Moreno",
"author_email": "Guillermo.RomeroMoreno@ed.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/e2/31/0643cbc9f7f0292d5236e22b5ab8bed5688564120960e78fa09c40655706/abc_network-0.1.3.tar.gz",
"platform": null,
"description": "# Associations Beyond Chance (ABC)\n\nThe ABC model provides a **Bayesian framework to infer multimorbidity associations between health conditions** from Electronic Health Records. The outputs are posterior distribution over pairwise association values, which can be assembled and visualised as multimorbidity weigthed network.\n\nThe ABC model was presented on the article [*\"Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups\"*](https://authors.elsevier.com/sd/article/S2352396424001166). This repository also provides code to reproduce the experiments and visualisations there. If you use this code, please cite the paper:\n\n> Romero Moreno G., Restocchi V., Fleuriot JD., Anand A., Mercer SW., Guthrie B. (2024). [*Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups*](https://www.sciencedirect.com/science/article/pii/S2352396424001166); **eBioMedicine**, Volume 102, 105081, ISSN 2352-3964, https://doi.org/10.1016/j.ebiom.2024.105081.\n\n```\n@article{ROMEROMORENO2024105081,\ntitle = {Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups},\njournal = {eBioMedicine},\nvolume = {102},\npages = {105081},\nyear = {2024},\nissn = {2352-3964},\ndoi = {https://doi.org/10.1016/j.ebiom.2024.105081},\nurl = {https://www.sciencedirect.com/science/article/pii/S2352396424001166},\nauthor = {Guillermo {Romero Moreno} and Valerio Restocchi and Jacques D. Fleuriot and Atul Anand and Stewart W. Mercer and Bruce Guthrie},\n}\n```\n\n\n\n\n## Installation and dependencies\n\nYou can install and use the package just by running `python setup.py install`. (It is recommended to perform the installation in a python virtual environment.)\n\nOr alternatively:\n\n- Install [Anaconda](https://docs.anaconda.com/) (if not already installed) \n- Execute `conda env create -n ABC --file packages.yml`* in a terminal for creating an environment called `ABC` with all the required packages. *Be aware that it may take a few GB of space.*\n- Activate the environment with `conda activate ABC`, and run the code or set up a jupyter notebook server (by running `jupyter notebook`)\n\n> .* Or you can directly execute `conda create -n ABC -c conda-forge numpy=1.22.3 scipy=1.8.0 pandas=1.4.2 matplotlib=3.5.1 seaborn=0.13.1 networkx=2.8 bokeh=3.3.0 cmdstanpy=1.1.0 jupyter`.\n\nWhile the code is in *python*, Bayesian inference is performed via [Stan](http://mc-stan.org) through the package `cmdstanpy` (version 1.1.0), providing a python API to the *Stan* library. The model (defined in the file [`ABC/models/MLTC_atomic_hyp_mult.stan`](ABC/models/MLTC_atomic_hyp_mult.stan)) could also work with [any stan interface](https://mc-stan.org/users/interfaces/index.html).\n\n## Using the model\n\nOur model can be used simply by running `ABC \"path/to/dataset_file.csv\"`, which will fit the model and generate output files with the results. For more information on additional argumnets, run `ABC --help`.\n\nAdditionally, you can integrate our model into other *python* code directly. You can see an example snippet on how to do so below.\n\n```python\nfrom ABC.model import ABCModel\nfrom ucimlrepo import fetch_ucirepo \n\n# This loads an example dataset. Swap these lines for those loading your dataset\ndataset = fetch_ucirepo(name='CDC Diabetes Health Indicators')\ndata = pd.concat([dataset.data.features, dataset.data.targets ], axis=1)\nbin_vars = dataset.variables[dataset.variables[\"type\"] == \"Binary\"][\"name\"].to_list()\n# Make sure to use columns with binary variables only\n\nmodel = ABCModel()\nmodel.load_fit(data, \"choose_name_for_model\", column_names=bin_vars, num_warmup=500, num_samples=2000, random_seed=1)\n\nABC = model.get_associations() # This retrieves the whole distribution for all association pairs\nresults = model.get_results_dataframe(credible_inteval_pvalue=0.01) # This creates a table with summary statistics\n```\n\nA detailed example with **step-by-step intructions** on how to use the model and produce outputs and visualisations within python code can be found at the tutorial notebook ['ABC_to_ABC.ipynb'](notebooks/ABC_to_ABC.ipynb).\n\n\n## Reproducing results\n\nYou can replicate the results and figures from the [*\"Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups\"*](https://authors.elsevier.com/sd/article/S2352396424001166) article by running the notebook [`notebooks/results.ipynb`](notebooks/results.ipynb). However, note that this will only be possible if you have access to the dataset used in the study.\n\nYou can still reproduce the results shown in that notebook on a different dataset, for which you will need to adapt all functions and variables within the file [`ABC/data.py`](ABC/data.py) to your dataset characteristics and then rerun [`notebooks/results.ipynb`](notebooks/results.ipynb) --- or use the functions in the file [`ABC/results.py`](ABC/results.py).\n\n\n## Repository structure\n\n* [`ABC/`](ABC/): python files with the basic classes and functions.\n* [`ABC/models/`](ABC/models/): files defining *Stan* models.\n* [`ABC/output/`](ABC/output/): folder in which to save the fitted models.\n* [`notebooks/`](notebooks/): results and examples implementing our models and code.\n* [`figs/`](figs/): folder in which to save the figures produced in the notebooks.\n\n\n## Acknowledgements\n\nFunctions and notebooks were inspired by [this repository](https://github.com/jg-you/plant-pollinator-inference/tree/master).\n\n\n### Contact\n\nAny question, comment, or feedback, contact <Guillermo.RomeroMoreno@ed.ac.uk>, or submit an Issues on GitHub.\n",
"bugtrack_url": null,
"license": "GNU GENERAL PUBLIC LICENSE",
"summary": "This package provides code linked to the paper \"Multimorbidity analysis with low condition counts: a robust Bayesian approach for small but important subgroups\" <https://authors.elsevier.com/sd/article/S2352396424001166>.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/Juillermo/ABC.git"
},
"split_keywords": [
"bayesian",
" multimorbidity"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4848aaabf09d0c373d00c77d17b57153e7093ded0047d69e502d4e7aac416c13",
"md5": "0fd1be4dda1feb97d4f6bc1937f30488",
"sha256": "dd7a2a8087deb2a6cb1b3650a2a6ac16d82ca59635f343c0395058a7eab5d4b2"
},
"downloads": -1,
"filename": "abc_network-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fd1be4dda1feb97d4f6bc1937f30488",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 46841,
"upload_time": "2024-04-17T16:20:12",
"upload_time_iso_8601": "2024-04-17T16:20:12.577447Z",
"url": "https://files.pythonhosted.org/packages/48/48/aaabf09d0c373d00c77d17b57153e7093ded0047d69e502d4e7aac416c13/abc_network-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e2310643cbc9f7f0292d5236e22b5ab8bed5688564120960e78fa09c40655706",
"md5": "ecd8dcde08320c3dd4a1df7a7ae85e8c",
"sha256": "55997f654923662f90f87af15557ba7e9a9590b4260dd99cee928b631273df9c"
},
"downloads": -1,
"filename": "abc_network-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ecd8dcde08320c3dd4a1df7a7ae85e8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 44679,
"upload_time": "2024-04-17T16:20:14",
"upload_time_iso_8601": "2024-04-17T16:20:14.973555Z",
"url": "https://files.pythonhosted.org/packages/e2/31/0643cbc9f7f0292d5236e22b5ab8bed5688564120960e78fa09c40655706/abc_network-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-17 16:20:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Juillermo",
"github_project": "ABC",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "abc-network"
}
JSON
