ASTHERISC (Algorithmic Search of THERmodynamic advantages In stoichiometric Single-species Community models)
This repository contains the ASTHERISC package, a CellNetAnalyzer-based MATLAB package implementation of the ASTHERISC algorithm. ASTHERISC's aim is to find target metabolites with a higher optimal minimal driving force in a situation were multiple strains of the same species interact than in a situation where a single strain has to produce it alone. ASTHERISC is explained in more detail in its PLOS Computational Biology publication (Bekiaris & Klamt, 2021).
This packages's sister program CommModelPy, which creates community models in a widely automated fashion, can be found here.
In order to run the ASTHERISC package, you need the following prerequisites:
- MATLAB in a version >= 2018a
- The MATLAB package CellNetAnalyzer in a version >=2019.1 which is available from here
- The CPLEX solver in a version >=12.8
As a point of reference for compatible prerequisity versions, ASTHERISC was successfully tested with the following configurations (although ASTHERISC might also work well with other versions and version combinations, this was just not tested):
- MATLAB 2018a & CellNetAnalyzer 2019.2 & CPLEX 12.8
- MATLAB 2018a & CellNetAnalyzer 2019.2 & CPLEX 12.9
- MATLAB 2019b & CellNetAnalyzer 2020.3 & CPLEX 12.10
Once you have installed CellNetAnalyzer in a configuration which allows it to use the CPLEX solver as it is explained in CellNetAnalyzer's manual, you have to add the following lines to "startcna.m" in CellNetAnalyzer's main folder (where $CPLEX_FOLDER has to be replaced by the folder where you installed CPLEX):
cnan.cplex_remote.transport_name= 'processtransport';
cnan.cplex_remote.transport_args= {'$CPLEX_FOLDER/cplex/bin/x86-64_linux/cplex', '-worker=process'};
Once you've done this, you can run the ASTHERISC package as follows:
- Download this repository and put it into a folder called "0Astherisc" in CellNetAnalyzer's main folder
- Start CellNetAnalyzer as described in its manual
- Add the ASTHERISC package's folder to MATLAB's path
Now, the installation is done \o/ and you can use the ASTHERISC package's functions as described in the next section.
The ASTHERISC package was developed for stoichiometric single-species community models which were generated by CommModelPy. The ASTHERISC package and CommModelPy were written by the same author and were firstly described in the same publication (Bekiaris & Klamt, 2021).
The ASTHERISC package's primary script file is "astherisc.m" which can be found in this repository's main folder. The usage of "astherisc.m", such as all neccessary arguments, is described in more detail in its source code header comment.
In addition, the other important script for the general user is "loadAndSaveCommModelPyCommunityModel.m". It reads a) a CommModelPy-generated community model in the SBML format and b) a JSON containing the dG0 data for the model's reactions and stores it as a combined .mat file which is the necessary model with dG0 data format for "astherisc.m". This script's usage is also explained in more detail in its source code header comment.
The JSON containing the dG0 values generally has to be structured as follows in the case of a two-strain community (in a models with a higher number strains, you have to add the specific reaction ids in the other species):
{
"$REACTION_1_ID_IN_SPECIES_1": {
"dG0": $dG0_VALUE_REACTION_1,
"uncertainty": $UNCERTAINTY_VALUE_REACTION_1
},
"$REACTION_1_ID_IN_SPECIES_2": {
"dG0": $dG0_VALUE_REACTION_1,
"uncertainty": $UNCERTAINTY_VALUE_REACTION_1
},
"$REACTION_2_ID_IN_SPECIES_1": {
"dG0": $dG0_VALUE_REACTION_1,
"uncertainty": $UNCERTAINTY_VALUE_REACTION_1
},
(...)
}
For example, if the CommModelPy-generated model has two reactions called A (with a dG0 of -5 and an uncertainty of 1) and B (with a dG0 of 10 and an uncertainty of 2), three strains with the labels "species1", "species2" and "species3", the JSON would look like this:
{
"A_species1": {
"dG0": -5,
"uncertainty": 1
},
"A_species2": {
"dG0": -5,
"uncertainty": 1
},
"A_species3": {
"dG0": -5,
"uncertainty": 1
},
"B_species1": {
"dG0": 10,
"uncertainty": 2
},
"B_species2": {
"dG0": 10,
"uncertainty": 2
},
"B_species3": {
"dG0": 10,
"uncertainty": 2
}
}
All ASTHERISC package-associated scripts which were run for the generation of the data in (Bekiaris & Klamt, 2021) are included in the "publication_runs" subfolder:
- The subfolder "./publication_runs/toy_model" contains the script for the generation of the shown toy model analysis and the result file itself.
- The subfolder "./publication_runs/ecoli_models" contains all analysis scripts and used run result text reports (in the local subfolder "run_results") for ecolicore2double, ecolicore2triple and iML1515double, including all 24 scenarios with a maximal MILP run time of 1000 s as well as the exemplary two runs with a maximal MILP run time of 10000 s.
Each shown run in the publication was performed using the MATLAB scripts starting with "run__". Statistics about the publication run result text reports, which were also the basis for the tables in the publication's Results section, can be generated using the "publication_run_result_statistics.py" Python script. Additionally, the ComModelPy-generated SBML models were converted into .mat files using "loadAndSavePublicationCommunityModelsAsMat.m" and are stored in the "models_and_dG0_data" subfolder where one can find the .mat files, the original SBML files and the JSONs containing the used dG0 data.
A report of the exact given 3-Deoxy-D-manno-octulosonate 8-phosphate (kdo8p) synthesis example in ASTHERISC's publication can be directly created with the "kdo8p_example.m" script, in which only the reactions used in the shown example are allowed. The reason for this separated script is that, depending on the CPLEX version and computational capability of the used computer or cluster, other alternative results for the kdo8p synthesis may arise, although all of them are equally valid since they reach the same optimal MDF. In other words, the kdo8p synthesis example given in ATHERISC's publication may arise as well as other possibilities to enhance the OptMDF in the given range.
The subfolder "submodules" contains scripts which are internally used by "astherisc.m".
The ASTHERISC package is described and used in the following publication:
This project is free and open-source, using the Apache License Version 2.0.
The origin of any data from external sources which are included in this package is given in the respective SOURCES.txt files.