cnapy-org/cnapy

An integrated visual environment for metabolic modeling with common methods such as FBA, FVA and Elementary Flux Modes, and advanced features such as thermodynamic methods, extended Minimal Cut Sets, OptKnock, RobustKnock, OptCouple and more!

CNApy: An integrated environment for metabolic modeling

Introduction

If you have questions, suggestions or bug reports regarding CNApy, you can use either of the CNApy GitHub issues, the CNApy GitHub discussions or the CNApy Gitter chat room.

CNApy is a Python-based graphical user interface for a) many common methods of Constraint-Based Reconstruction and Analysis (COBRA) with stoichiometric metabolic models, b) the visualization of COBRA calculation results and c) the creation and editing of metabolic models.

Supported COBRA methods (partly provided by cobrapy) include:

• Flux Balance Analysis (FBA)
• Flux Variability Analysis (FVA)
• Making measured flux scenarios stoichiometrically feasible
• Elementary Flux Modes (EFM)
• Thermodynamic methods based on OptMDFpathway
• Many advanced strain design algorithms such as OptKnock, RobustKnock, OptCouple and advanced Minimal Cut Sets through its integration of the StrainDesign package
• Yield optimization (based on linear-fractional programming)
• Phase plane analysis

All calculation results can be visualized in CNApy's interactive and editable metabolic maps. These maps can also use vector-based (SVG) backgrounds. Escher maps are also natively supported and can be created and edited inside CNApy.

Aside of performing calculations on metabolic models, CNApy can also be used to create and/or edit metabolic models. This includes all important aspects of the model's reactions, metabolites and genes. For model loading and export, CNApy supports the widely used SBML standard format.

For more details on CNApy's many more features, see section Documentation and Tutorials.

For information about how to install CNApy, see section Installation Options.

For information about how to contribute to CNApy as a developer, see section Contribute to the CNApy development.

If you want to cite CNApy, see section How to cite CNApy.

Associated project note: If you want to use the well-known MATLAB-based CellNetAnalyzer (CNA), which is not compatible with CNApy, you can download it from CNA's website.

Documentation and Tutorials

• The CNApy guide contains information for all major functions of CNApy.
• Our CNApy YouTube channel provides some videos of working with CNApy.
• We also provide directly usable CNApy example projects which include some of the most common E. coli models. These projects can also be downloaded within CNApy at its first start-up or via CNApy's File menu.

Installation Options

There are 4 alternative ways to install CNApy:

1. If you use Windows, the easiest way is to use our Windows installer, see section Using the Windows installer.
2. If you use Linux or Apple MacOS X, the easiest installation producure is our assisted installation protocol, see Assisted installation under Linux and MacOS X.
3. If you already have installed Anaconda, Miniconda or Miniforge on your computer, you can directly install CNApy as a conda package as described in section Install CNApy as conda package.
4. If you want to develop CNApy, follow the instruction for the cloning and setup of the CNApy repository using git and conda or mamba in section Setup the CNApy development environment.

Contribute to the CNApy development

Everyone is welcome to contribute to CNApy's development. See our contribution file for more detailed instructions.

Using the Windows installer

1. Download the zipped CNApy Windows installer from here.
2. Unzip the file into your desired location. You can do this by right-clicking on the file and selecting the option to extract the files.
3. In the location where you unzipped the file, click on "INSTALL_CNAPY.bat"; This installation procedure only works with an active internet conncection. As soon as the installation is finished, the appearing window closes and you can start CNApy either by double-clicking on the newly created CNApy shortcut on your desktop (which also shows CNApy's logo) or the newly created RUN_CNAPY.bat in the folder where INSTALL_CNAPY.bat lies. If CNApy is not starting, this might have been caused by an internet connection problem; Running "INSTALL_CNAPY.bat" again might solve the problem. To uninstall CNApy, double-click on the UNINSTALL_CNAPY.bat in the same folder.

Assisted installation under Linux and MacOS X

Click on the operating system you use:

• Linux
• Apple MacOS X

Assisted Linux installation

1. Download Miniforge from here.
2. Install Miniforge by double-clicking the downloaded file. If the script does not run, right-click on the file, open its settings and select the option to make it executable (alternative: run 'chmod u+x ./Miniconda3-latest-Linux-x86_64.sh' in your terminal). Follow the appearing installation instructions and remember in which folder you install Miniconda. Note: If you already have installed Anaconda on your computer before (for which we also directly provide a conda CNApy package, see here), deactivate all installation options which put Miniconda to your console or system PATH to avoid possible problems.
3. Using your file manager, go to the folder where you installed Miniforge. Then, open the appearing sub-folder "condabin".
4. Download the CNApy installation assistant script from here into the mentioned "condabin" folder.
5. In the file manager, double-click on the newly downloaded installation assistant script which is called "cnapy-assistant-script.sh". If the script does not run, right-click on the file, open its settings and select the option to make it executable or, alternatively, run 'chmod u+x ./cnapy-assistant-script.sh' in your terminal in the mentioned "condabin" folder. Wait until CNApy is downloaded and installed.
6. You can now run CNApy by executing the following two terminal instructions in the mentioned "condabin" folder:

./conda activate cnapy-1.1.11
cnapy

If you installed Miniforge system-wide, it's also possible to run these commands in any other terminal folder.

Assisted MacOS X installation

1. If you have a (new) Mac with an ARM processor, such as the M1, M2 or M3, download Miniconda from here. If you have an (older) Mac with an Intel processor, download Miniconda from here. If you are unsure which processor your Mac has, click on the Apple menu in the upper-left of your screen and choose "About This Mac". Note: Currently, if you want to use the CPLEX solver within CNApy, you have to install the Intel processor version of Miniconda regardless of your Mac's processor. This is caused by the lack of a CPLEX ARM Python package (see also this issue for more details).
2. Install Miniconda by double-clicking the downloaded file. Follow the appearing installation instructions and remember in which folder you install Miniconda. Note: If you already use Anaconda on your computer (for which we directly provide a conda CNApy package, see here), deactivate all installation options which put Miniconda to your console or system PATH to avoid possible problems
3. Using Finder, go to the folder where you installed Miniconda. Then, open the appearing sub-folder "condabin".
4. Download the CNApy installation assistant script from here into the mentioned "condabin" folder.
5. In the file manager, double-click on the newly downloaded installation assistant script which is called "cnapy-installation-script.sh". If the script does not run, right-click on the file, open its settings and select the option to make it executable (alternative: run 'chmod u+x ./cnapy-assistant-script.sh' in your terminal). Wait until CNApy is downloaded and installed.
6. Open the terminal in the mentioned "condabin" folder. You can now run CNApy by executing the following two terminal instructions:

./conda activate cnapy-1.1.11
cnapy

Install CNApy as conda package

Note for Mac users (does not affect Windows or Linux users): Currently, if you want to use the CPLEX solver within CNApy, you have to install the Intel processor version of Anaconda/Miniconda/Miniforge regardless of your Mac's processor. This is caused by the lack of a CPLEX ARM Python package (see also this issue for more details).

Note for all users: If you've installed mamba on your system (e.g., with Miniforge), it is the recommended way to install CNApy as it is much faster than conda. To use mamba, just replace the "conda" command in the following steps with "mamba".

1. Create a conda environment with all dependencies

   conda create -n cnapy-1.1.11 -c Gurobi -c IBMDecisionOptimization -c conda-forge -c cnapy cnapy=1.1.11 --yes

2. Activate the cnapy conda environment

   conda activate cnapy-1.1.11

3. Run CNApy within you activated conda environment

   cnapy

Furthermore, you can also perform the following optional steps:

4. (optional and only possible if you have already installed CNApy by using conda) If you already have a cnapy environment, e.g., cnapy-1.X.X, you can delete it with the command

   # Here, the Xs stand for the last CNApy version you've installed by using conda
   conda env remove -n cnapy-1.X.X

5. (optional, but recommended if you also use other Python distributions or Anaconda environments) In order to solve potential package version problems, set a systems variable called "PYTHONNOUSERSITE" to the value "True".

   Under Linux systems, you can do this with the following command:

   export PYTHONNOUSERSITE=True

   Under Windows systems, you can do this by searching for your system's "environmental variables" and adding the variable PYTHONNOUSERSITE with the value True using Window's environmental variables setting window.

Setup the CNApy development environment

We use conda as package manager to install all dependencies. You can use miniconda. If you have conda installed you can:

1. Create a conda development environment with all dependencies

   conda env create -n cnapy-dev -f environment.yml

2. Activate the development environment

   conda activate cnapy-dev

3. Checkout the latest cnapy development version using git

   git clone https://github.com/cnapy-org/CNApy.git

4. Change into the source directory and run CNApy

   cd CNApy
   python cnapy.py

Any contribution intentionally submitted for inclusion in the work by you, shall be licensed under the terms of the Apache 2.0 license without any additional terms or conditions.

How to cite CNApy

If you use CNApy in your scientific work, please consider to cite CNApy's publication:

Thiele et al. (2022). CNApy: a CellNetAnalyzer GUI in Python for analyzing and designing metabolic networks. Bioinformatics 38, 1467-1469, doi.org/10.1093/bioinformatics/btab828.

cnapy's Issues

add reset scenario function

The coefficient in obj function for reaction is not saved

Rename reactions in SmallExample2

P:ex -> R3

Add function to interrupt long running computations

Show annotations from the sbml model in the reaction/species properties

• We do read and show the cobra annotation for reactions.

But cobra does it's own parsing of the annotations

<reaction id="R_ULA4Ntppi" fast="false" reversible="false" name="Transport (cytoplasm to periplasm)" metaid="R_ULA4Ntppi" sboTerm="SBO:0000185" fbc:upperFluxBound="cobra_default_ub" fbc:lowerFluxBound="cobra_0_bound">
  <sbml:annotation xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="#R_ULA4Ntppi">
        <bqbiol:is xmlns:bqbiol="http://biomodels.net/biology-qualifiers/">
          <rdf:Bag>
            <rdf:li rdf:resource="http://identifiers.org/bigg.reaction/ULA4Ntppi"/>
            <rdf:li rdf:resource="http://identifiers.org/metanetx.reaction/MNXR105114"/>
            <rdf:li rdf:resource="http://identifiers.org/seed.reaction/rxn09357"/>
          </rdf:Bag>
        </bqbiol:is>
      </rdf:Description>
    </rdf:RDF>
  </sbml:annotation>

and is returning a bunch of identifiers

{'sbo': 'SBO:0000185', 'bigg.reaction': 'ULA4Ntppi', 'metanetx.reaction': 'MNXR105114', 'seed.reaction': 'rxn09357'}

I have no idea how we could get our metadata into this scheme.

Set threshhold for unboundedness when using model bounds while efm computation

• enable text entry on checking checkbox
• set default to 100

Add possibility to optimize flux for a specific reaction via right click on the reaction box

Save and load mcs computation setting

The buttons are disabled for now.

Generalize scenarios as set of linear constraints

Currently a scenario is only a set of fixed reaction rates.
In future it would be nice to allow complex constraints like in this example.

Write a manual

use this wiki https://github.com/ARB-Lab/CNApy/wiki/CNApy-User-Manual

Save/show/edit additional infos like comments or delta g_0

Either like cobrapy in the SBML annotations (as RDF) or in a separate file which would be included in the cna project/archive.
Here a list of CNA specific reaction attributes:

• deltaGR_0 : -35.68;
• deltaGR_Uncertainty : 7.97
• KEGG_ID : R08549
• BiGG_ID :AKGDH

and a list of CNA specific species attributes:

• BiGG_ID : 4crsol_p
• Universal_BiGG_ID : 4crsol
• KEGG_ID :
• CHEBI_ID : CHEBI:44726
• Formula : C23H34N7O17P3S
• Charge : NaN

Clear computed values on reset scenario

Add functionality to change model bounds to scenario values

Add yield optimization

Show a message if fba, fva, efm fail to find solutions for some reason

For the following cases we need a message box!

• FBA returns infeasible
• pFBA returns infeasible
• FVA returns infeasible
• EFM returns no modes
• MCS returns no cut sets

Color differently two cases of non equal bounds

1st case: bound do exclude 0 like (-inf,-1.0) or (1.,200)
2nd case: everything else

Improve console

Maybe use pyqtconsole?
pyqtconsole is using PyQt5 while we are using PySide2 as qt bindings also it has no conda package.
qtconsole looks like a larger more active project they also have conda packages and may work with PySide2 via qtpy.

Catch errors that happen if CNA path is wrong

Add menu entry to Save current project and ask for confirmation to overwrite

Add toolbar with important functions

• Clear scenario
• Restore scenario
• Turn heatmap coloring on
• Turn On/Off coloring on

add scenario highlighting on reactions

On = green = if v != 0

add fva from cobrapy

Save last used directory and use it when opening the next file dialog

Start with $User/CNA-projects.

Allow changing values directly in the reaction list view

Show gene product associations in UI

https://cobrapy.readthedocs.io/en/latest/getting_started.html#Genes

Restore Scenario after ModeNavigator has been closed

Elementary mode computation can consider 0 values in the scenario.
Maybe we should keep those and restore them after the ModeNavigator is closed.
Maybe make the "consider 0 values" option default.

Delete reaction from scenario if its last reaction box has been remove from the mapview

Don't know about this. I think it should probably only be removed if the reaction is removed. The scenario value would still be visible in the reaction list.
Related: Don't load scenario values for reactions that are not in the current model.

Change workflow for deleting maps

• remove close button on tabs
• add delete map button next to add map button

Save application state on exit and recover on next startup

• Last project file
• Last scenario
• Window position/size
• etc.

Add ability to change and apply changes to species

Allow to set feasibility tolerance in optlang

Needs investigation

Change default color for heat map from blue back to green

Set config option from UI

• CNA path
• Colors
• Shown number of digits after decimal point
• Defaultcolor : Qt.gray
• self.abs_tol : 0.0001
• Working directory should better be set to last used(open/save) directory

add Clipboard like in CNA

Change workflow to switch to reaction properties dialog from mapview

Instead of double click on a reaction box in the map view add a entry to the context menu of the reaction box.

add clear scenario function

Add possibility to right click on map to add reactions

Integrate MCS computation via duality

Basic version is working. This needs the cnapy_compute_mcs.m from CellNetAnalyzer master.

Add functionality to show model bounds as values like FVA results

Compute/show basic model properties

• Number of reactions, metabolites
• Stoichiometric matrix infos
• conservation relations
• degrees of freedom
• smallest/largest absolute value > 0 in matrix

STOICHIOMETRIC MATRIX (without external metabolites):
     6 internal (balanced) metabolites (rows)
     10 reactions (columns), thereof 2 reversible
     Rank of stoichiometric matrix: 6
          --> No conservation relation(s) exist.
     Degrees of freedom: 4
 
     Smallest (absolute) non-zero-value: 1
     Largest (absolute) value: 1
 
     Network can be compressed to (isozymes not considered): 
          2 metabolites 
          6 reactions (thereof 2 reversible)

• Model Annotations

Compute In/Out fluxes at a metabolite

I think this should be reimplemented in python. It looks like the glue code would be more than the current implementation.

Fix bug in float comparison

Only flux ranges that exclude 0 should be painted green

Add possibility to navigate model. Jump from reactions to metabolites and the other way

add pfba from cobrapy

Cleanup examples directory

New structure simply projects

SmallExample2 - SmallExample2.cna
              - Smallexample2-map1.map
              - scenario1.scen
              - background-map1.svg
              - verycool.modes
...

add search box for reactions

Save default scenario within the project data

Not sure yet how this is done best.
In some sense the bounds on the models reaction represent itself a scenario.
Should constraints from an default scenario would overwrite these bounds?

Example: in the model has reaction R the bounds -10>=,<=5
in the scenario the bounds are set to 6>=,<=10.

I see two ways to interpret this situation and I'm not yet sure which to choose:

1. If i give both constraints there would be no solution.
2. if the scenario replaces the models constraint there are solutions

Compute net conversion of external metabolites

net_conversion.m uses get_rates.m which grabs the values from the CNA map.

Add functionality to add all values to the scenario

Add functionality to remove unused species

I see 3 approaches

1. automatically remove unused species if the model changes
2. add a function to remove unused species on demand
3. add a button to remove species manually