From fb68af5b57d404554975a1ac3638c352d539663e Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Tue, 19 Aug 2025 11:24:35 +0200 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20Update=20README=20with=20add?= =?UTF-8?q?iitonal=20sections=20and=20remove=20Contrib=20info,=20which=20w?= =?UTF-8?q?ill=20be=20ina=20separate=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 86 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 0a00dc7..bef2807 100644 --- a/README.md +++ b/README.md @@ -21,55 +21,79 @@ GitHub stars

-The integration of metagenomic data from multiple studies and experimental conditions is essential to understand the interactions between microbial communities in complex biological systems, but the inherent diversity and biological complexity pose methodological challenges that require refined strategies for atlas-level integration. ABaCo, a family of generative models based on Variational Autoencoders (VAEs) combined with an adversarial training, aim for the integration of metagenomic data from different studies by minimizing technical heterogeneity conserving biological significance. The VAE encodes the data into a latent space, while the discriminator is trained to detect the provenance of the data, eliminating variability associated with its origin; concurrently, the data is modeled using distributions suitable for raw counts, and the latent space follows a clustering prior to ensure biological conservation. - -An overview of the ABaCo workflow is shown in the figure below: - -![ABaCo Abstract](https://raw.githubusercontent.com/Multiomics-Analytics-Group/abaco/HEAD/docs/images/abaco_overview.png) - ## Table of Contents +- [About the project](#about-the-project) - [Installation](#installation) - [Features](#features) - [Usage](#usage) - [Documentation](#documentation) -- [Contributing](#contributing) - [License](#license) +- [Contributing](#contributing) +- [Credits and acknowledgements](#credits-and-acknowledgements) +- [Contact and feedback](#contact-and-feedback) + +## About the project + +The integration of metagenomic data from multiple studies and experimental conditions is essential to understand the interactions between microbial communities in complex biological systems, but the inherent diversity and biological complexity pose methodological challenges that require refined strategies for atlas-level integration. ABaCo, a family of generative models based on Variational Autoencoders (VAEs) combined with an adversarial training, aim for the integration of metagenomic data from different studies by minimizing technical heterogeneity conserving biological significance. The VAE encodes the data into a latent space, while the discriminator is trained to detect the provenance of the data, eliminating variability associated with its origin; concurrently, the data is modeled using distributions suitable for raw counts, and the latent space follows a clustering prior to ensure biological conservation. + +An overview of the ABaCo workflow is shown in the figure below: + +![ABaCo Abstract](https://raw.githubusercontent.com/Multiomics-Analytics-Group/abaco/HEAD/docs/images/abaco_overview.png) + +## Installation + +> [!TIP] +> It is recommended to install ABaCo inside a virtual environment to manage depenendencies and avoid conflicts with existing packages. You can use the virtual environment manager of your choice, such as `poetry`, `conda`, or `pipenv`. + +### Pip -## Installation +ABaCo is available on [PyPI][abaco-pypi] and can be installed using pip: -ABaCo is available on PyPI: ```bash pip install abaco ``` +You can also install the package for development by cloning this repository and running the following command: + +> [!WARNING] +> We assume you are in the root directory of the cloned repository when running this command. Otherwise, you need to specify the path to the `abaco` directory. + +```bash +pip install -e . +``` + ## Features ## Usage ## Documentation -Tutorials and documentation are available on [Read the Docs](https://mona-abaco.readthedocs.io/) -## Contributing -1. Fork the repository -2. Clone the repository -3. Create a virtual env e.g. - ```bash - # navigate terminal to repo - cd - - # create virtual env - python -m venv .venv - - # activate venv - source .venv/bin/activate - ``` -4. Install abaco in editing mode into the virtual env - ```bash - pip install -e . - ``` -5. Make changes - > Note: we aimt o use numpy style python docstrings [sphinx example](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy) -6. Make a pull request +ABaCo's documentation is hosted on [Read the Docs][abaco-docs]. It includes detailed examples, configuration options, and the API reference. ## License + +The code in this repository is licensed under the **MIT License**, allowing you to use, modify, and distribute it freely as long as you include the original copyright and license notice. + +The documentation and other creative content are licensed under the **Creative Commons Attribution 4.0 International (CC BY 4.0) License**, meaning you are free to share and adapt it with proper attribution. + +Full details for both licenses can be found in the [LICENSE][abaco-license] file. + +## Contributing + +ABaCo is an open-source project, and we welcome contributions of all kinds via GitHub issues and pull requests. You can report bugs, suggest improvements, propose new features, or implement changes. Please follow the guidelines in the [CONTRIBUTING](CONTRIBUTING.md) file to ensure that your contribution is easily integrated into the project. + +## Credits and acknowledgements + +- ABaCo was developed by the [Multiomics Network Analytics Group (MoNA)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain]. + +## Contact and feedback + +We appreciate your feedback! If you have any comments, suggestions, or run into issues while using ABaCo, feel free to [open an issue][new-issue] in this repository. Your input helps us make ABaCo better for everyone. + +[abaco-pypi]: https://pypi.org/project/abaco/ +[abaco-license]: https://github.com/Multiomics-Analytics-Group/abaco/blob/main/LICENSE.md +[abaco-docs]: https://mona-abaco.readthedocs.io/ +[Mona]: https://multiomics-analytics-group.github.io/ +[Biosustain]: https://www.biosustain.dtu.dk/ +[new-issue]:https://github.com/Multiomics-Analytics-Group/abaco/issues/new From 08af9a2b5dfa98e885a653a0b3649c3aaf19b435 Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Tue, 19 Aug 2025 11:25:12 +0200 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=84=20Update=20license=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- LICENSE | 22 ---------------------- LICENSE.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 22 deletions(-) delete mode 100644 LICENSE create mode 100644 LICENSE.md diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 88a548a..0000000 --- a/LICENSE +++ /dev/null @@ -1,22 +0,0 @@ -MIT License - -Copyright (c) 2025: First Last. - -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. diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..3503576 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,31 @@ +## MIT License + +Copyright (c) 2025 Multi-omics Network Analytics Group + +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. + +## Creative Commons Attribution 4.0 International License (CC BY 4.0) + +Copyright (c) 2025 Multi-omics Network Analytics Group + +The creative works from this project are licensed under a Creative Commons Attribution +4.0 International License. + +To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/. + From eea46ab9339ea506409bc5c4a374588f4183d68f Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Tue, 19 Aug 2025 11:25:37 +0200 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Create=20CONTRIBUTING.md=20f?= =?UTF-8?q?ile?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cd02d6e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to ABaCo + +[ABaCo][abaco-repo] is an open source project, and we welcome contributions of all +kinds via GitHub issues and pull requests: correct or improve our [documentation][abaco-docs], report or fix bugs, propose changes, and implement new features. Please follow +these guidelines to make sure that your contribution is easily integrated into the project. + +## 1. Contributor Agreement + +By contributing, you agree that we may redistribute your work under [our +license](LICENSE.md). In exchange, we will address your issues and/or assess +your change proposal as promptly as we can, and help you become a member of our +community. + +## 2. What to Contribute + +The easiest way to get started is by reporting an issue that needs to be fixed, +such as a bug in the code, unclear explanations, conceptual errors, or other details. +You can also contribute by proposing new features or modules, improving existing +functionality, or suggesting other ideas that might be useful. If you’re looking for +inspiration, please check the [list of open issues][issues] in this repository. + +Feedback from beginners is especially valuable, as experienced users may overlook how +challenging certain aspects of the software can be for newcomers. Therefore, we encourage +you to share any suggestions or observations you have about this project. + +## 3. How to Contribute + +Here are the ways you can submit your suggestions and contribute to the project: + +### 1. Reporting Issues or Suggesting Improvements + +If you have a [GitHub][github] account (or are willing to [open one][github-join]) but are unfamiliar with Git, you can report bugs or suggest improvements by [creating an issue][new-issue]. This GitHub feature allows for discussion threads on reported issues and proposed enhancements. + +### 2. Submitting Changes via Pull Requests + +If you are comfortable using Git and would like to add or modify a functionality, you can submit a **pull request (PR)**. Instructions on how to contribute this way are provided in the next section. + +> [!NOTE] +> The documentation for [Git][git-docs] and [GitHub][github-docs] are easy to follow, and you can learn the basics using their official guides. + +## 3. Creating a Pull Request + +If you choose to contribute via GitHub, you may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we use [GitHub flow][github-flow] to manage changes: + +1. Create a new branch in your desktop copy of this repository for each significant change. +2. Commit the change in that branch. +3. Push that branch to your fork of this repository on GitHub. +4. Submit a pull request from that branch to the [upstream repository][abaco-repo]. +5. If you receive feedback, make changes on your desktop and push to your branch on GitHub: the + pull request will update automatically. + +## 5. Credits + +This contribution guide was modified under the [Creative Commons Attribution 4.0 International License][ccby] from the [Software Carpentry guides][soft-cp-guides]. + +[abaco-repo]: https://github.com/Multiomics-Analytics-Group/abaco +[abaco-docs]: https://mona-abaco.readthedocs.io/ +[issues]: https://github.com/Multiomics-Analytics-Group/abaco/issues +[new-issue]: https://github.com/Multiomics-Analytics-Group/abaco/issues/new +[github]: https://github.com +[github-join]: https://github.com/join +[git-docs]: https://git-scm.com/doc +[github-docs]: https://guides.github.com/ +[how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github +[github-flow]: https://guides.github.com/introduction/flow/ +[soft-cp-guides]: https://software-carpentry.org/lessons/ +[ccby]: https://creativecommons.org/licenses/by/4.0/