=========================================================== Modelling and Inference of MICrobiomes Project (MIMIC)

.. image:: https://codecov.io/gh/ucl-cssb/MIMIC/graph/badge.svg?token=O3J4X6ECIQ :target: https://codecov.io/gh/ucl-cssb/MIMIC

Overview

MIMIC: A Comprehensive Python Package for Simulating, Inferring, and Predicting Microbial Community Interactions

The study of microbial communities is vital for understanding their impact on environmental, health, and technological domains. The Modelling and Inference of MICrobiomes Project (MIMIC) introduces a Python package designed to advance the simulation, inference, and prediction of microbial community interactions and dynamics. Addressing the complex nature of microbial ecosystems, MIMIC integrates a suite of mathematical models, including previously used approaches such as Generalized Lotka- Volterra (gLV), Gaussian Processes (GP), and Vector Autoregression (VAR), plus newly developed models for integrating multiomic data, to offer a comprehensive framework for analysing microbial dynamics. By leveraging Bayesian inference and machine learning techniques, MIMIC accurately infers the dynamics of microbial communities from empirical data, facilitating a deeper understanding of their complex biological processes, unveiling possible unknown ecological interactions, and enabling the design of microbial communities. Such insights could help to advance microbial ecology research, optimizing biotechnological applications, and contributing to environmental sustainability and public health strategies. MIMIC is designed for flexibility and ease of use, aiming to support researchers and practitioners in microbial ecology and microbiome research. This software package contributes to microbial ecology research and supports ecological predictions and applications, benefiting the scientific and applied microbiology communities.

Structure

The repository is organized into the following main directories:

• AUTHORS.rst: A list of authors and contributors to the project.
• build/: Contains files generated by the build process.
• CONTRIBUTING.rst: Guidelines for contributing to the project.
• dist/: Contains distribution packages.
• docs/: Contains the project's documentation and Sphinx sources.
  • docs/source/notebooks/: Jupyter notebooks categorized by model type.
• examples/: Contains example scripts and notebooks demonstrating how to use the package.
• HISTORY.rst: A log of changes made in each version of the project.
• LICENSE: The license for the project.
• mimic/: The main directory for the project's source code.
  • data_imputation/: Data imputation-related modules.
  • model_infer/: Inference models.
  • model_simulate/: Simulation models.
  • utilities/: Utility scripts.
• README.rst: The main README file for the project, providing an overview and basic usage examples.
• environment.yml: The Conda environment file for macOS and Ubuntu.
• environment_windows.yml: The Conda environment file for Windows.
• requirements.in: The pip requirements input file.
• requirements.txt: The compiled list of Python dependencies.
• setup.py: The build script for the project.
• tests/: Contains unit tests for the project's code.
• .github/: Contains GitHub templates and workflows.

Installation

Prerequisites ^^^^^^^^^^^^^

• Conda Package Manager: We recommend using Conda to manage the environment due to dependencies that may not be available via pip.

Installation Steps ^^^^^^^^^^^^^^^^^^^

For macOS and Ubuntu """"""""""""""""""""

1. Clone the Repository

   .. code-block:: bash

   git clone https://github.com/ucl-cssb/MIMIC.git cd MIMIC

2. Create the Conda Environment

   .. code-block:: bash

   conda env create -f environment.yml

3. Activate the Environment

   .. code-block:: bash

   conda activate mimic_env

4. Install the Package

   .. code-block:: bash

   pip install -e .

5. Run the Code

   Refer to the Usage_ section below for instructions on how to run the code.

For Windows """""""""""

1. Clone the Repository

   .. code-block:: bash

   git clone https://github.com/ucl-cssb/MIMIC.git cd MIMIC

2. Create the Conda Environment for Windows

   On Windows, use the environment_windows.yml file:

   .. code-block:: bash

   conda env create -f environment_windows.yml

3. Activate the Environment

   .. code-block:: bash

   conda activate mimic_env

4. Install the Package

   Install the package in editable mode:

   .. code-block:: bash

   pip install -e .

5. Run the Code

   Refer to the Usage_ section below for instructions on how to run the code.

Alternative Installation Using Pip Only ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you prefer to use pip without Conda, you can install the package and its dependencies by compiling requirements.in into requirements.txt:

.. code-block:: bash

Step 1: Compile requirements.txt from requirements.in

pip install pip-tools pip-compile requirements.in

Step 2: Install dependencies

pip install -r requirements.txt pip install -e .

Note: This method may not install all dependencies correctly, especially if there are packages that are only available via Conda. We recommend using the Conda installation method for full functionality.

Compilers """"""""""" A g++ compiler is required for the PyMC3 package.

Usage

To get started with MIMIC, you can explore a variety of detailed examples and comprehensive documentation.

• Documentation: Visit our complete documentation for detailed guides and more.
• Examples: Check out our Examples Directory which includes Jupyter notebooks demonstrating how to use MIMIC for different applications and scenarios.

The documentation is regularly updated with the latest information on usage, features, and examples to help you effectively utilize the MIMIC package in your research or applications.

Contributing

We welcome contributions to the MIMIC project. Please refer to our Contribution Guidelines <CONTRIBUTING.rst>_ for more information.

License

This project is licensed under the LICENSE <LICENSE>_.

Acknowledgements

This project is based on methods proposed in this paper <https://onlinelibrary.wiley.com/doi/full/10.1002/bies.201600188>_.

Contact

For questions or feedback, please contact us <mailto:christopher.barnes@ucl.ac.uk>_.