Mentions légales du service

Skip to content
Snippets Groups Projects

CoCoMiCo : COoperation and COmpetition in MIcrobial COmmunities

CoCoMiCo aims at characterising the metabolism of microbial communities through genome-scale metabolic networks: it calculates cooperation and competition potentials for the communities.

It has four modes:

  • a command-line mode community, where analyses are performed on communities defined using command-line arguments,
  • a batch mode specification, where analyses are performed according to JSON specification files, formatted as described below,
  • a CWL mode entrypoint, designed to be called by CWL workflows using the definitions in tools/, and
  • an example mode example, that runs CoCoMiCo on a bundled example community.

Install

Required Python >= 3.10. The main dependency of CoCoMiCo is an Answer Set Programming (ASP) solver. Clyngor manages the connection between Python and ASP; the Clyngor_with_clingo package includes the solver binaries in the Python environment so that they do not need to be installed separately. If you work in a Conda environment, installing the solvers directly (clingo) makes it unnecessary to install Clyngor_with_clingo.

Install from Pypi using

pip install cocomico

or after cloning this repository

pip install .

If you use CoCoMiCo, please cite:

Lecomte M, Muller C, Badoual A, Falentin H, Sherman DJ, and Frioux C. 2023. CoCoMiCo: metabolic modelling of cooperation and competition potentials in large-scale bacterial communities.

Usage

Single community run

community defines a single community on the command line, and expects SBML-formatted metabolic network files in a single directory:

Community_folder
├── species_1.sbml
├── species_4.sbml
├── species_10.sbml
Usage: cocomico community [OPTIONS] [MODEL]...

  CoCoMiCo for a community defined by the MODELs, or by all models in
  sbml_dir.

Options:
  --output PATH                   Directory to write output, created if
                                  necessary
  --seeds-file PATH               SBML file defining seed biomolecules
  --seeds-def TEXT                Comma-separated list of seed biomolecules
  --sbml-dir DIRECTORY            Directory containing SBML model files
  --csv-output PATH               Path to write CSV output
  --header-csv / --no-header-csv  Add header to CSV output
  --name TEXT                     Community name (and default output filename
                                  stem)
  --json-output PATH              Path to write a single JSON output or '-'
  --help                          Show this message and exit.

Example execution

cocomico community
    --seeds-def M_E_c,M_F_c,M_X1_c
    --seeds-file seeds.sbml
    --json-output results.json
    --csv-output results.csv
    sbml/Com2Org*.sbml

Multiple communities using a specification

specification uses a JSON-formatted specification file to define collections of communities defined over a set of SBML model files:

Folder_input
├── communities.json
├── sbml
│   └── species_1.sbml
│   └── species_4.xml
|    ..

`communities.json`` must be in the following format:

{
    "com_0" :[
            species_1.sbml,
            species_4.sbml,
            species_10.sbml
    ],
    "com_1" :[
            species_12.sbml,
            species_120.sbml
    ]
}

Here, sample community com0 is composed of three species: species_, species_4 and species_10.

Usage: cocomico specification [OPTIONS]

  CoCoMiCo for all communites defined by a specification file.

Options:
  --output PATH                   Directory to write output, created if
                                  necessary
  --seeds-file PATH               SBML file defining seed biomolecules
  --seeds-def TEXT                Comma-separated list of seed biomolecules
  --sbml-dir DIRECTORY            Directory containing SBML model files
  --csv-output PATH               Path to write CSV output
  --header-csv / --no-header-csv  Add header to CSV output
  --spec PATH                     JSON file that specifies communities
  --help                          Show this message and exit

Example execution

cocomico specification
    --spec communities.json
    --seeds-file seeds.sbml
    --output results

Bundled example

CoCoMiCo bundles a simple example that can be run without supplying input SBML models.

Usage: cocomico example [OPTIONS]

  CoCoMiCo for a small example community.

  cocomico example --output results

Options:
  --output PATH  Directory to write output, created if necessary
  --help         Show this message and exit.

Run using CWL

CWL CommandLineTool definitions are provided for CoCoMiCo in tools/cocomico/.

To run CoCoMiCo in single community mode, use cocomico.cwl and supply a job file like cocomico_job.yaml that specifies which model files to include in the community:

cwltool --verbose --no-container \
    tools/cocomico/cocomico.cwl tools/cocomico/cocomico_job.yaml

The job file specifies which output to compute, in the example results.json and results.csv.

To run CoCoMiCo in specification mode, use cocomico_spec.cwl and supply a job file like cocomico_spec_job.yaml that specifies a specification file:

cwltool --verbose --no-container \
    tools/cocomico/cocomico_spec.cwl tools/cocomico/cocomico_spec_job.yaml

The CWL definitions assume that software requirements are already met, so the Python virtual environment must be activated, and CoCoMiCo installed. If a CWL runner is not already installed on your system, you can add the reference implementation using pip install cwltool or conda install cwltool.

Record provenance in a RO-Crate

The cwltool reference implementation can record result provenance in a Research Object Crate:

cwltool --provenance ro-crate --verbose --no-container \
    tools/cocomico/cocomico_spec.cwl tools/cocomico/cocomico_spec_job.yaml

The RO-Crate will contain the results, a packed CWL workflow, metadata describing the CoCoMiCo execution, and a copy of the input data.

The recorded results always can be reconstructed by rerunning the workflow:

cwltool --no-container workflow/packed.cwl workflow/primary-job.json

Output

Summary results will be reported in a single tab-separated CSV file, for example

community  seeds               delta  coop  rho   comp  comp_num  coop_num  coop_prod  coop_cons
com_0      M_E_c,M_F_c,M_X1_c  12     9.0   21    0.6   1         4         4.5        4.5
com_1      M_E_c,M_F_c,M_X1_c  19     17.0  35    1.0   2         8         8.5        8.5
com_2      M_E_c,M_F_c,M_X1_c  5      2.0   10    1.0   1         1         1.0        1.0

The analysis for each community will be a JSON file containing, for example:

{
    "models": [
        "Com1Org1.sbml",
        "Com1Org2.sbml",
        "Com1Org3.sbml"
    ],
    "results": [
        {
            "activated": [  ],
            "competition": [
                0.6666666666666666,
                {
                    "competition": 0.6666666666666666,
                    "number of polyopsonist metabolites": 1
                }
            ],
            "consumed_seeds": [
                "M_E_c",
                "M_F_c",
                "M_X1_c"
            ],
            "cooperation": [
                9.0,
                {
                    "coop bonus consumers": 4.5,
                    "coop bonus producers": 4.5,
                    "cooperation": 9.0,
                    "number of exchanged metabolites": 4
                }
            ],
            "delta": [
                12,
                {
                    "added value community": 12,
                    "sum community scope": 23,
                    "sum individual scope": 11
                }
            ],
            "exchange": {
                "M_A_c": {
                    "consumers": [
                        "Com1Org3"
                    ],
                    "producers": [
                        "Com1Org2"
                    ]
                },
                "M_B_c": {
                    "consumers": [
                        "Com1Org1"
                    ],
                    "producers": [
                        "Com1Org3"
                    ]
                },
                "M_C_c": {
                    "consumers": [
                        "Com1Org2",
                        "Com1Org3"
                    ],
                    "producers": [
                        "Com1Org1",
                        "Com1Org3"
                    ]
                },
                "M_Y_c": {
                    "consumers": [
                        "Com1Org3"
                    ],
                    "producers": [
                        "Com1Org2"
                    ]
                }
            },
            "monopsonist": {
                "M_A_c": 1,
                "M_B_c": 1,
                "M_Y_c": 1
            },
            "polyopsonist": {
                "M_C_c": 2
            },
            "produced_seeds": [
                "M_F_c"
            ],
            "rho": [
                21,
                {
                    "added activated community": 21,
                    "sum community activated": 38,
                    "sum individual activated": 17
                }
            ],
            "scope": [  ],
            "seeds": [
                "M_E_c",
                "M_F_c",
                "M_X1_c"
            ]
        }
    ],
    "sbml_dir": "example/sbml",
    "taxa": [
        "Com1Org1",
        "Com1Org2",
        "Com1Org3"
    ]
}

Logging

Each step of the analysis is logged to the console. The default log level is INFO. To show a detailed trace, specify a log level of DEBUG. To only show warnings or worse, specify a log level of WARN.

cocomico --loglevel=WARN community --seeds-def M_E_c,M_F_c,M_X1_c sbml/Com2Org*.sbml

Random sampling

CoCoMiCo includes sample-communities, a utility for generating community specification files using stratified random sampling from multiple sources. Sources can be directories of SBML models, or community specifications. If more than one source is given, equal numbers of models will be chosen from each source: the stratified samples are uniform., rounded out by choosing from a pool. If a pool is not provided explicitly, then it is made by combining all sources.

You must specify the sizes of the communities, and the number of reps of each size. Unique sample names are generated by hashing their members, but can also be generated sequentially from a name prefix.

To help with cross validation, samples can be completed with a leave-one-out and an add-one-in strategy. For each sample of size N, N leave-one-out samples and reps add-one-in samples will be generated in addition to the original samples.

The sample command generates one sample of communities.

sample-communities sample --dest mix --size 10 leaf root soil
sample-communities sample --dest mix --size 10 --source leaf --source root --source soil

sample-communities sample --dest eco --size 10 ecosystem_*.json
sample-communities sample --dest av-gut --added-value --pool sbml --source sample/gut
sample-communities sample --dest av-max --added-value --source mix.json

The sample-chain command builds samples iteratively.

sample-communities \
  sample-chain --dest mix --size 10 --source leaf --source root \
  sample-chain --dest eco --size 10 --added-value --source mix

sample-communities sample-chain --dest av --added-value --pool sbml --source sample/gut

Run sample-communities --help for detailed options.

CWL CommandLineTool definitions for sampling are provided tools/cocomico/.

Version

CoCoMiCo version 0.3.2