# ageml
`ageml` is a Python package for Age Modelling with Machine Learning made easy.
[](https://zenodo.org/doi/10.5281/zenodo.10255549) [](https://badge.fury.io/py/ageml) 
## Background
Age Modelling consists of trying to predict the chronological age of an organism with a set of features that capture information about its aging status and dynamics. With a rich feature set one can accurately predict the chronological age of a normative (healthy) population using relatively simple machine learning models. When the feature set is sufficiently rich and the model can capture the complexity of the data, performing inference on non-normative populations leads to prediction errors in their chronological age. The mismatch between the chronological vs. predicted age (known as _age delta_) is a proxy of aberrant aging trajectories, often having high correlations with factors that condition ageing. Furthermore, classification of different clinical groups (e.g.: stable vs progressive) can also be done using the trained models.
## Description
`ageml` allows age modelling with a set of simple-to-use CLIs that produce comprehensive figures of the modelling steps and detailed logs for exploring the effectiveness of the trained models.
There are 4 main CLIs:
- __model_age__: It takes a features file (in CSV format) from a set of subjects, which includes their chronological age, and it trains a model for predicting it. Categorical Covariates can be included to train models per category, using a CSV file. Systems, feature groups that correspond to a congruent physiological system (cardiac, muskuloskeletal, gastric, etc.) can also be included to train models per system using a simple .txt file. A CSV file is returned with the predicted ages, and the corresponding _age delta_. Also, a simple correlation analysis is performed to check how the input features correlate with the chronological age. The age distribution of the cohort is plotted too.
- __factor_correlation__: The correlation between the provided factors and the computed _age deltas_ is analyzed, including the strength and significance. If the clinical category of each subject is provided (with a CSV file), this analysis runs for every clinical category.
- __clinical_groups__: To see how the _age delta_ changes across clinical groups, a boxplot is created. The age distribution across the groups is also plotted.
- __clinical_classify__: Using the features file and the ages file (with the _age delta_) classification of two clinical groups is performed. A Receiver Operating Curve (ROC) is plotted for each model used in the classifications.
## How to install `ageml`
#### Using `pip` (recommended)
From your terminal, for basic installation, run: `pip install ageml`
#### Cloning from Github
Note that `ageml` is under active development, but still not continuously deployed, so the latest version might not be available in PyPI. If you want to use the latest version, you can clone the repository and install it locally.
From your terminal, run: `git clone https://github.com/compneurobilbao/ageml.git`
Then `cd` into the `ageml` folder, and install with pip:`pip install .`
#### Docker
There are two Dockerfiles available for `ageml`.
- One that installs `ageml` from pip -> ./Dockerfile
- Another one for the latest version of `ageml`, which installs it from the GitHub repo `main` branch.
To build the pip image, run:
`docker build -t ageml:pip -f Dockerfile <path_to_directory_containing_Dockerfile>`
To build the latest image, run:
`docker build -t ageml:latest -f Dockerfile <path_to_directory_containing_Dockerfile>`
To run the container, run:
`docker run -it ageml:<tag_of_your_image>`
A developer Dockerfile will be available in the future for contributing to the project in a containerized fashion.
#### Developer installation
The developer installation is described in the [contribution guidelines](./docs/CONTRIBUTING.md).
## How to cite
If you use `ageml` in your work, please cite the all-time:
J. Garcia Condado, I. Tellaetxe Elorriaga, J. M. Cortes, and A. Erramuzpe, ‘AgeML: Age modelling with Machine Learning’. BioRxiv. May 05, 2024. doi: 10.1101/2024.05.02.592130.
```
@article{ageml_2024,
title = {AgeML: Age modelling with Machine Learning},
author = {Garcia Condado, Jorge and Tellaetxe Elorriaga, Iñigo and Cortes, Jesus M. and Erramuzpe, Asier},
url = {http://biorxiv.org/lookup/doi/10.1101/2024.05.02.592130},
doi = {10.1101/2024.05.02.592130},
month = may,
year = {2024},
}
```
## How to Contribute to the project
We welcome scientists and developers who want to standardize the procedures of age modelling, share pretrained models or whatever other kind of contribution that can help the project.
The contribution guidelines can be found [here](./docs/CONTRIBUTING.md).
## How to use `ageml`
A comprehensive, step by step tutorial of the tool can be found [here](./docs/TUTORIAL.md).
You can also tinker around with our [getting started Colab notebook](https://colab.research.google.com/drive/1FtHbIghXLswG8IcOgFZBHJ07wKnLuzbG?authuser=3) if you want a more interactive experience.
## Motivation
BrainAge models (Franke et al. 2010, Neuroimage) have had success in exploring the relationship between healthy and pathological ageing of the brain. Furthermore, this type of age modelling can be extended to multiple body systems and modelling of the interactions between them (Tian et al 2023, Nature Medicine).
However, there is no standard for age modelling. There have been works attempting to describe proper procedures, especially for age-bias correction (de Lange and Cole 2020, Neuroimage: Clinical). In this work we developed an Open-Source software that allows anyone to do age modelling following well-established and tested methodologies for any type of clinical data. Age modelling with machine learning made easy.
The objective of `ageml` is to standardise procedures, lower the barrier to entry into age modelling and ensure reproducibility. The project is Open-Source to create a welcoming environment and a community to work together to improve and validate existing methodologies. We are actively seeking new developers who want to contribute to growing and expanding the package.
References:
- De Lange, A.-M. G., & Cole, J. H. (2020). Commentary: Correction procedures in brain-age prediction. NeuroImage: Clinical, 26, 102229. [https://doi.org/10.1016/j.nicl.2020.102229](https://doi.org/10.1016/j.nicl.2020.102229)
- Franke, K., Ziegler, G., Klöppel, S., & Gaser, C. (2010). Estimating the age of healthy subjects from T1-weighted MRI scans using kernel methods: Exploring the influence of various parameters. NeuroImage, 50(3), 883–892. [https://doi.org/10.1016/j.neuroimage.2010.01.005](https://doi.org/10.1016/j.nicl.2020.102229)
- Tian, Y. E., Cropley, V., Maier, A. B., Lautenschlager, N. T., Breakspear, M., & Zalesky, A. (2023). Heterogeneous aging across multiple organ systems and prediction of chronic disease and mortality. Nature Medicine, 29(5), 1221–1231. [https://doi.org/10.1038/s41591-023-02296-6](https://doi.org/10.1016/j.nicl.2020.102229)
## License
This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](./LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/compneurobilbao/ageml",
"name": "ageml",
"maintainer": "jorge.garcia.condado",
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": "jorgegarciacondado@gmail.com",
"keywords": "Machine Learning, Age Modelling, Brain Age",
"author": "Computational Neuroimaging Lab Bilbao, IIS Biobizkaia",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e0/e6/c1214ab2d98eacea76c9868f3d0936856abe166ec589948fd23b711fabf2/ageml-0.2.0.tar.gz",
"platform": null,
"description": "# ageml\n\n`ageml` is a Python package for Age Modelling with Machine Learning made easy.\n\n[](https://zenodo.org/doi/10.5281/zenodo.10255549) [](https://badge.fury.io/py/ageml) \n\n## Background\n\nAge Modelling consists of trying to predict the chronological age of an organism with a set of features that capture information about its aging status and dynamics. With a rich feature set one can accurately predict the chronological age of a normative (healthy) population using relatively simple machine learning models. When the feature set is sufficiently rich and the model can capture the complexity of the data, performing inference on non-normative populations leads to prediction errors in their chronological age. The mismatch between the chronological vs. predicted age (known as _age delta_) is a proxy of aberrant aging trajectories, often having high correlations with factors that condition ageing. Furthermore, classification of different clinical groups (e.g.: stable vs progressive) can also be done using the trained models.\n\n## Description\n\n\n`ageml` allows age modelling with a set of simple-to-use CLIs that produce comprehensive figures of the modelling steps and detailed logs for exploring the effectiveness of the trained models.\n\nThere are 4 main CLIs:\n\n- __model_age__: It takes a features file (in CSV format) from a set of subjects, which includes their chronological age, and it trains a model for predicting it. Categorical Covariates can be included to train models per category, using a CSV file. Systems, feature groups that correspond to a congruent physiological system (cardiac, muskuloskeletal, gastric, etc.) can also be included to train models per system using a simple .txt file. A CSV file is returned with the predicted ages, and the corresponding _age delta_. Also, a simple correlation analysis is performed to check how the input features correlate with the chronological age. The age distribution of the cohort is plotted too.\n- __factor_correlation__: The correlation between the provided factors and the computed _age deltas_ is analyzed, including the strength and significance. If the clinical category of each subject is provided (with a CSV file), this analysis runs for every clinical category.\n- __clinical_groups__: To see how the _age delta_ changes across clinical groups, a boxplot is created. The age distribution across the groups is also plotted.\n- __clinical_classify__: Using the features file and the ages file (with the _age delta_) classification of two clinical groups is performed. A Receiver Operating Curve (ROC) is plotted for each model used in the classifications.\n\n## How to install `ageml`\n\n#### Using `pip` (recommended)\n\nFrom your terminal, for basic installation, run: `pip install ageml`\n\n#### Cloning from Github\n\nNote that `ageml` is under active development, but still not continuously deployed, so the latest version might not be available in PyPI. If you want to use the latest version, you can clone the repository and install it locally. \n\nFrom your terminal, run: `git clone https://github.com/compneurobilbao/ageml.git` \nThen `cd` into the `ageml` folder, and install with pip:`pip install .`\n\n#### Docker\nThere are two Dockerfiles available for `ageml`.\n- One that installs `ageml` from pip -> ./Dockerfile\n- Another one for the latest version of `ageml`, which installs it from the GitHub repo `main` branch.\n\nTo build the pip image, run:\n`docker build -t ageml:pip -f Dockerfile <path_to_directory_containing_Dockerfile>`\nTo build the latest image, run:\n`docker build -t ageml:latest -f Dockerfile <path_to_directory_containing_Dockerfile>`\n\nTo run the container, run:\n`docker run -it ageml:<tag_of_your_image>`\n\nA developer Dockerfile will be available in the future for contributing to the project in a containerized fashion.\n\n#### Developer installation\n\nThe developer installation is described in the [contribution guidelines](./docs/CONTRIBUTING.md).\n\n## How to cite\n\nIf you use `ageml` in your work, please cite the all-time:\n\nJ. Garcia Condado, I. Tellaetxe Elorriaga, J. M. Cortes, and A. Erramuzpe, \u2018AgeML: Age modelling with Machine Learning\u2019. BioRxiv. May 05, 2024. doi: 10.1101/2024.05.02.592130.\n\n```\n\n@article{ageml_2024,\n title = {AgeML: Age modelling with Machine Learning},\n author = {Garcia Condado, Jorge and Tellaetxe Elorriaga, I\u00f1igo and Cortes, Jesus M. and Erramuzpe, Asier},\n url = {http://biorxiv.org/lookup/doi/10.1101/2024.05.02.592130},\n doi = {10.1101/2024.05.02.592130},\n month = may,\n year = {2024},\n}\n```\n\n## How to Contribute to the project\n\nWe welcome scientists and developers who want to standardize the procedures of age modelling, share pretrained models or whatever other kind of contribution that can help the project.\n\nThe contribution guidelines can be found [here](./docs/CONTRIBUTING.md).\n\n## How to use `ageml`\n\nA comprehensive, step by step tutorial of the tool can be found [here](./docs/TUTORIAL.md).\nYou can also tinker around with our [getting started Colab notebook](https://colab.research.google.com/drive/1FtHbIghXLswG8IcOgFZBHJ07wKnLuzbG?authuser=3) if you want a more interactive experience.\n\n## Motivation\n\nBrainAge models (Franke et al. 2010, Neuroimage) have had success in exploring the relationship between healthy and pathological ageing of the brain. Furthermore, this type of age modelling can be extended to multiple body systems and modelling of the interactions between them (Tian et al 2023, Nature Medicine).\n\nHowever, there is no standard for age modelling. There have been works attempting to describe proper procedures, especially for age-bias correction (de Lange and Cole 2020, Neuroimage: Clinical). In this work we developed an Open-Source software that allows anyone to do age modelling following well-established and tested methodologies for any type of clinical data. Age modelling with machine learning made easy.\n\nThe objective of `ageml` is to standardise procedures, lower the barrier to entry into age modelling and ensure reproducibility. The project is Open-Source to create a welcoming environment and a community to work together to improve and validate existing methodologies. We are actively seeking new developers who want to contribute to growing and expanding the package.\n\nReferences:\n\n- De Lange, A.-M. G., & Cole, J. H. (2020). Commentary: Correction procedures in brain-age prediction. NeuroImage: Clinical, 26, 102229. [https://doi.org/10.1016/j.nicl.2020.102229](https://doi.org/10.1016/j.nicl.2020.102229)\n- Franke, K., Ziegler, G., Kl\u00f6ppel, S., & Gaser, C. (2010). Estimating the age of healthy subjects from T1-weighted MRI scans using kernel methods: Exploring the influence of various parameters. NeuroImage, 50(3), 883\u2013892. [https://doi.org/10.1016/j.neuroimage.2010.01.005](https://doi.org/10.1016/j.nicl.2020.102229)\n- Tian, Y. E., Cropley, V., Maier, A. B., Lautenschlager, N. T., Breakspear, M., & Zalesky, A. (2023). Heterogeneous aging across multiple organ systems and prediction of chronic disease and mortality. Nature Medicine, 29(5), 1221\u20131231. [https://doi.org/10.1038/s41591-023-02296-6](https://doi.org/10.1016/j.nicl.2020.102229)\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0 - see the [LICENSE](./LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "AgeML is a Python package for Age Modelling with Machine Learning made easy.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/compneurobilbao/ageml",
"Repository": "https://github.com/compneurobilbao/ageml"
},
"split_keywords": [
"machine learning",
" age modelling",
" brain age"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb6e2d235ffcbda44fac96ac7cc1c4b06649d1220cdf5fe6886b1932ad3e0e33",
"md5": "32cb81c059ee5de1289d5aa3c3dc42b8",
"sha256": "66973b79e56578fef76b99c16ead0944a2ffebc1e8cb4db780e6aebe2673fb7e"
},
"downloads": -1,
"filename": "ageml-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32cb81c059ee5de1289d5aa3c3dc42b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 202676,
"upload_time": "2024-09-24T09:15:37",
"upload_time_iso_8601": "2024-09-24T09:15:37.125021Z",
"url": "https://files.pythonhosted.org/packages/fb/6e/2d235ffcbda44fac96ac7cc1c4b06649d1220cdf5fe6886b1932ad3e0e33/ageml-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0e6c1214ab2d98eacea76c9868f3d0936856abe166ec589948fd23b711fabf2",
"md5": "0e7ee6d5e600ee05e2a7ebddb8e6d0bd",
"sha256": "6bcb41cb0ebf305c35da30983ab90c5f5514e8144e922301448ed59eddaf34da"
},
"downloads": -1,
"filename": "ageml-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0e7ee6d5e600ee05e2a7ebddb8e6d0bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 202543,
"upload_time": "2024-09-24T09:15:38",
"upload_time_iso_8601": "2024-09-24T09:15:38.869525Z",
"url": "https://files.pythonhosted.org/packages/e0/e6/c1214ab2d98eacea76c9868f3d0936856abe166ec589948fd23b711fabf2/ageml-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-24 09:15:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "compneurobilbao",
"github_project": "ageml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ageml"
}
JSON
