COBRA Tutorials

Overview

The COBRA.tutorials repository exists to collect and maintain tutorials for developed and published constraint-based genome-scale modelling methods and studies. Its purpose is to provide clear, reproducible instructional material that demonstrates how new algorithms, workflows, and analysis techniques can be applied within the COBRA modelling framework. By centralising these tutorials, the repository supports both new and experienced users in learning, comparing, and adopting state-of-the-art constraint-based modelling approaches.

Repository structure

Tutorials are here to get you started with using The COBRA Toolbox. The tutorials are grouped according to the src/ folder structure:

• analysis
• base
• dataIntegration
• design
• reconstruction
• visualization

All tutorials are provided in these formats: .mlx, .m, and .html.

• The interactive version .mlx is a MATLAB Live Script format and can be run using the MATLAB Live-script editor.
• The static version .html is automatically generated and is accessible on the tutorial section of the COBRA Toolbox documentation.
• The .pdf version can be downloaded from the same tutorial section. The .m version can be opened and run directly in MATLAB, which is particularly useful for building new analysis scripts based on existing tutorials.

How the Continuous Integration (CI) System Works

The COBRA.tutorials repository uses an automated continuous integration (CI) workflow. When a contributor pushes a new or updated .mlx tutorial to the repository:

1. The CI pipeline is automatically triggered.
2. The .mlx file is converted into three formats: - .m (MATLAB script) - .pdf (print-ready copy) - .html (web-friendly version)
3. These generated files are published to the COBRA Toolbox website, making the tutorial immediately accessible to users.

The diagram below illustrates this workflow:

Contribute a new tutorial or modify an existing tutorial

A template for generating a new tutorial is provided here.

There are two ways to contribute to the tutorials:

A) Contribute using git (via command line)

Fork and checkout your branch

1. Fork the COBRA.tutorials repository on Github.

2. Clone the forked repository to a directory of your choice:

   git clone git@github.com:<userName>/COBRA.tutorials.git fork-COBRA.tutorials.git

3. Change to the directory:

   cd fork-COBRA.tutorials.git/

4. Set the upstream to the opencobra/COBRA.tutorials repository:

   git remote add upstream git@github.com:opencobra/COBRA.tutorials.git

5. Fetch from the upstream repository:

   git fetch upstream

6. Checkout a new branch from upstream/master:

   git checkout -b master upstream/master

7. Now, make your changes to the tutorial in MATLAB.

Submit your changes and open a pull request to the master branch

8. Once you are done making changes, add the files to your branch (tutorial_<yourFile> refers to the tutorial name). Make sure to add the .mlx format of the tutorial.

   git add tutorial_<yourFile>.mlx
   git commit -m "Changes to tutorial_<yourFile>"

9. Push your commits on <yourBranch> to your fork:

   git push origin <yourBranch>

10. Browse to your fork on:

    • https://www.github.com/<yourUserName>/COBRA.tutorials

11. Click on Compare & Pull Request.

12. Confirm the target branch is master.

13. Submit your pull request.

14. Wait until your pull request is accepted.