{"id":19323408,"url":"https://github.com/cfrioux/miscoto","last_synced_at":"2025-07-29T22:34:23.080Z","repository":{"id":30743550,"uuid":"125871124","full_name":"cfrioux/miscoto","owner":"cfrioux","description":"Python package for large-scale community selection in microbiota","archived":false,"fork":false,"pushed_at":"2024-02-29T10:28:00.000Z","size":294,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-20T07:07:26.033Z","etag":null,"topics":["answer-set-programming","bioinformatics","microbiome","symbiont"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfrioux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-19T14:30:34.000Z","updated_at":"2025-06-04T03:36:45.000Z","dependencies_parsed_at":"2024-11-10T01:46:22.852Z","dependency_job_id":"d8e24164-e5bd-48cc-8e04-bd8523919088","html_url":"https://github.com/cfrioux/miscoto","commit_stats":{"total_commits":133,"total_committers":6,"mean_commits":"22.166666666666668","dds":0.6691729323308271,"last_synced_commit":"ce308c5351f275b0271db5daf09b73f20b120ea4"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/cfrioux/miscoto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfrioux%2Fmiscoto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfrioux%2Fmiscoto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfrioux%2Fmiscoto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfrioux%2Fmiscoto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfrioux","download_url":"https://codeload.github.com/cfrioux/miscoto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfrioux%2Fmiscoto/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266103459,"owners_count":23876809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["answer-set-programming","bioinformatics","microbiome","symbiont"],"created_at":"2024-11-10T01:46:19.659Z","updated_at":"2025-07-29T22:34:23.059Z","avatar_url":"https://github.com/cfrioux.png","language":"Python","readme":"[![PyPI version](https://img.shields.io/pypi/v/miscoto.svg)](https://pypi.org/project/Miscoto/) [![GitHub license](https://img.shields.io/github/license/cfrioux/miscoto.svg)](https://github.com/cfrioux/miscoto/blob/main/LICENSE) [![Actions Status](https://github.com/cfrioux/miscoto/workflows/Python%20package/badge.svg)](https://github.com/cfrioux/miscoto/actions) [![](https://img.shields.io/badge/doi-10.1093/bioinformatics/bty588-blueviolet.svg)](https://academic.oup.com/bioinformatics/article/34/17/i934/5093211)\n\n# MiSCoTo\n## Description\n**Microbiome Screening and COmmunity selection using TOpology**\n\nMiSCoTo is a Python3 (3.6 and higher) tool to explore microbiomes and select minimal communities within them.\nIt uses Answer Set Programming (ASP) to optimize community selection.\n\nMiSCoTo follows the producibility in metabolic networks as defined by the [network expansion](http://www.ncbi.nlm.nih.gov/pubmed/15712108) algorithm.\nMainly, two rules are followed:\n* a *recursive rule*: the products of a reactions are producible if **all** reactants of this reaction are themselves producible\n* an *initiation rule*: producibility is initiated by the presence of nutrients, called *seeds*. \n\nA metabolite that is producible from a set of nutrients is described as being \"in the scope of the seeds\".\nThe computation is made using logic solvers (Answer Set Programming). The present modelling ignores the stoichiometry of reactions (2A + B --\u003e C is considered equivalent to A + B --\u003e C), and is therefore suited to non-curated or draft metabolic networks.\n\nMiSCoTo computes the set of metabolites that are producible by a community (with or without a host). It can also compute minimal communities starting from a large community under a defined objective (production of targets by the community of by the host). \n\n**If you use MiSCoTo, please cite:** \n\n*Frioux C, Fremy E, Trottier C, Siegel A. Scalable and exhaustive screening of metabolic functions carried out by microbial consortia. Bioinformatics 2018;34:i934–43. [https://doi.org/10.1093/bioinformatics/bty588](https://doi.org/10.1093/bioinformatics/bty588).*\n\n**If you look for a wider screening of communities, as well as metabolic network reconstruction for a large set of genomes** please look at [Metage2Metabo](https://github.com/AuReMe/metage2metabo)\n\nInputs: metabolic models, seeds (growth medium) and metabolic targets as SBML files (see examples in [toy](https://github.com/cfrioux/miscoto/tree/main/toy)).\n\nComputations can be performed with a set of symbionts or a set of symbionts and a host. In the latter case, targets will be produced by the host, whereas in the former they will be produced by any member of the microbiota.\n\nImportant notice: be sure that two identical metabolites have the same name in all metabolic networks. Otherwise inconsistencies might occur between targets predicted as producible under the \"soup\" modeling and the \"minexch\" modeling.\n\n### Microbiome exploration\nComputation of the added value of the microbiota over a individual host with respect to targets or the whole scope of producible compounds.\n\nTool = `miscoto_scope.py`\n\n### Community selection\nCommunity selection uses parsimonious criteria:\n* **size minimization** under mixed-bag assumption (one virtual compartment for the whole microbiome)\n    * scales up to large microbiomes\n    * computation of one, all, union or intersection of all communities\n    * first step prior to exchange minimization to reduce the space of solutions\n* **size and exchange minimizations** under a compartmentalized framework\n    * computation of one, all, union or intersection of all communities and their associated exchanges\n    * more computationnally demanding: a first step of size minimization is preferred. Use one selected minimal-size community or their union (if not too large i.e. around 50 symbionts or less on personal computers) as symbiont inputs\n\nTool = `miscoto_mincom.py`\n\n## Install\n\n\nRequired package (starting from version 2.0 of the package):\n* [clyngor](https://github.com/Aluriak/clyngor) (``pip install clyngor==0.3.20``) or  ``clyngor-with-clingo`` (``pip install clyngor-with-clingo``)\n\n```\npip install miscoto\n```\n\n## Usage\n\n    usage: miscoto [-h] [-v] {instance,focus,mincom,scopes} ...\n\n    Explore microbiomes and select minimal communities within them. For specific\n    help on each subcommand use: miscoto {cmd} --help\n\n    optional arguments:\n    -h, --help            show this help message and exit\n    -v, --version         show program's version number and exit\n\n    subcommands:\n    valid subcommands:\n\n    {instance,focus,mincom,scopes}\n        instance            Prepares instance for miscoto.\n        focus               Focus on one species and determine what it can produce\n                            alone or in its community.\n        mincom              Compute a community from a microbiome.\n        scopes              Compute the scope and target produciblity of a host.\n\n    Requires Clingo and clyngor package: \"pip install clyngor clyngor-with-clingo\"\n\n* ``miscoto scopes`` compute the scope and target produciblity of a host (optional) and the added-\nvalue of a microbiome regarding scope and target producibility. The microbiome\nresult part gives the targets and compounds that are producible providing\ncooperation occurs within the community of host + all symbionts and that were\nnot producible with the host alone. Computation from SBML models or an\ninstance pre-created with miscoto_instance.py\n    * from SBML files\n\n        * usage 1: host, symbionts, seeds, [targets]\n        ```\n        miscoto scopes -m host.sbml -b symbiont_directory -s seeds.sbml -t targets.sbml [--output output_file]\n        ```\n        * usage 2: symbionts, seeds, [targets]\n        ```\n        miscoto scopes -b symbiont_directory -s seeds.sbml -t targets.sbml [--output output_file]\n        ```\n    * from a pre-computed instance with possibly (additional) seeds or targets\n        * usage 3: instance, [seeds], [targets]    \n        ```\n        miscoto scopes -a instance.lp [-s seeds.sbml] [-t targets.sbml] [--output output_file]\n        ```\n\n    ```miscoto scopes``` can be called directly in Python\n    ```python\n    from miscoto import run_scopes\n\n    run_scopes(lp_instance_file=xxx, targets_file=xxx, \\\n                seeds_file=xxx, bacteria_dir=xxx, \\\n                host_file=xxx, output_json=xxx)\n    ```\n\n* ``miscoto focus`` calculates the producible metabolites for one metabolic network of interest in\ntwo conditions. First when considered alone in the given nutritional\nconditions. Secondly, among its community, in the same nutritional conditions\nbut those are necesarily altered by what other species are likely to produce.\n\n    Please note that the name of the microbe of interest corresponds to the basename of its corresponding file in the symbionts input directory, e.g. for a file named\n    `ecoli.sbml`, the given basename must be `ecoli`.\n\n        -h, --help            show this help message and exit\n        -b BACTSYMBIONTS, --bactsymbionts BACTSYMBIONTS\n                                directory of symbionts models, all in sbml format\n        -s SEEDS, --seeds SEEDS\n                                seeds in SBML format\n        -f FOCUS, --focus FOCUS\n                                basename of the metabolic network to be analysed in\n                                the community\n        --output OUTPUT       output file in json\n        --all                 focus on all bacteria of the community\n\n\n    ```miscoto focus``` can be called directly in Python\n    ```python\n    from miscoto import run_focus\n\n    run_focus(bacteria_dir=xxx, \\\n                seeds_file=xxx, focus_bact=xxx, \\\n                output_json=xxx, all_networks=False)\n    ```\n\n\n* ``miscoto mincom`` computes a community from a microbiome Inputs: SBML models (symbionts and\noptionally host) + seeds + targets or an instance pre-created with\nmiscoto_instance.py, option: soup = minimal size community in a mixed-bag\nframework or minexch = minimal size and minimal exchange community. Can\ncompute one minimal solution and or union, intersection, enumeration of all\nminimal solutions\n    * from SBML files \n        * usage 1: host, symbionts, seeds, targets  \n        ```\n        miscoto mincom -m host.sbml -b symbiont_directory -s seeds.sbml -t targets.sbml -o option [--intersection] [--union] [--enumeration] [--optsol] [--output output_file]\n        ```\n        * usage 2: symbionts, seeds, targets\n        ```\n        miscoto mincom -b symbiont_directory -s seeds.sbml -t targets.sbml -o option [--intersection] [--union] [--enumeration] [--optsol] [--output output_file]\n        ```\n\n    * from a pre-computed instance with possibly (additional) seeds or targets \n        * usage 3: instance, [seeds], [targets]   \n        ```\n        miscoto mincom -a instance.lp -o option [-s seeds.sbml] [-t targets.sbml] [--intersection] [--union] [--enumeration] [--optsol] [--output output_file]\n        ```\n    ```miscoto mincom``` can be called directly in Python\n    ```python\n    from miscoto import run_mincom\n\n    run_mincom(option='soup/minexch', \\\n                bacteria_dir=xxx, host_file=xxx,\\\n                targets_file=xxxx, seeds_file=xxx,\\\n                optsol=True/False, enumeration=True/False, \\\n                intersection=True/False, union=True/False, \\\n                output_json=xxx)\n\n    run_mincom(option='soup/minexch', \\\n                bacteria_dir=xxx, \\\n                targets_file=xxxx, seeds_file=xxx,\\\n                optsol=True/False, enumeration=True/False, \\\n                intersection=True/False, union=True/False, \\\n                output_json=xxx)\n\n    run_mincom(option='soup/minexch',\\\n                lp_instance_file=xxxx,\\\n                targets_file=xxxx, seeds_file=xxx,\n                optsol=True/False, enumeration=True/False, \\\n                intersection=True/False, union=True/False, \\\n                output_json=xxx)\n    ```\n\nUsing the `output_json` option, it is possible to create a json output file with these keys:\n\n    * bacteria: bacteria in the optimal solution\n    * still_unprod: unproducible compounds by the community\n    * newly_prod: newly producible compounds by the community\n    * union_bacteria: bacteria from all the minimal communities\n    * inter_bacteria: bacteria from the intersection of all the minimal communities\n    * one_model: results of the optimal solution\n    * union_exchanged: all the exchanged compounds\n    * inter_exchanged: intersection of the exchanged compounds\n    * exchanged: exchanged compounds in the optimal solution\n    * key_species: bacteria from all the minimal communities\n    * essential_symbionts: bacteria from the intersection of all the minimal communities\n    * alternative_symbionts: bacteria appearing in at least one minimal community but not in all (if intersection and union options are used)\n    * targets_producers: for each target, the list of organisms able to produce this target in the full community with `miscoto_scopes` and in the selected minimal communities with `miscoto_mincom`\n\n## Benchmark tips\n\nFor the screening of large communities, ASP-compliant instances can be pre-generated and easily modified to save time by avoiding the reading of all SBML files.\nThe instance can be modified (usable bacteria with the predicate ``bacteria(\"xxx\").``, targets with predicates ``target(\"xxx\").`` or seeds with predicates ``seeds(\"xxx\").`` for example) using bash commands (e.g. sed) at each run.\n\n``miscoto_instance.py`` creates such instance:\n\n```\nmiscoto instance [-h] [-m MODELHOST] -s SEEDS [-t TARGETS] -b BACTSYMBIONTS [-o OUTPUT]\n```\n\n```python\nfrom miscoto import run_instance\n\nrun_instance(bacteria_dir=xxx, seeds_file=xxx, host_file=xxx, targets_file=xxxx, output=xxx)\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfrioux%2Fmiscoto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfrioux%2Fmiscoto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfrioux%2Fmiscoto/lists"}