gba 0.6.4

gbapy (Growth Balance Analysis for Python)

Growth Balance Analysis for Python

     

    

---

pip install gba

gbapy is a Python package that provides tools for building and analyzing self-replicating cell (SRC) models based on the growth balance analysis (GBA) mathematical formalism (Dourado et al. 2023). This approach, built exclusively on the first principles of fitness maximization, mass conservation, nonlinear reaction kinetics, and constant cell density, allows to study resource allocation in models of whole self-replicating cells (Dourado et al. 2025).

The module offers two core components:

• :wrench: A builder class, to construct SRC models of any size from first principles,
• :chart_with_upwards_trend: A model class, to manipulate and optimize models once they are built.

[!TIP] Start by reading the complete description of GBA formalism, then follow the tutorials below to learn the required format:

• SRC models must comply to a standardized format. Guidelines are available in the 🔗 Toy model tutorial.
• When building a SRC model, stoichiometric coefficients, and kinetic parameters must be converted following GBA formalism. See the 🔗 Units conversion tutorial.

Table of contents

• Get started with a typical workflow
• Installation
  • Supported platforms
  • Dependencies
  • Manual installation
• Documentation
• Contributing
• Copyright
• License

Get started with a typical workflow

In this first step, you build the structure of a simple SRC model from scratch. The Builder object is used to declare the main biological entities of the system, define how they interact through reactions, and specify the external conditions that will later be tested during optimization.

from gba import Builder, Model, Protein, Metabolite, Reaction
from gba import SpeciesLocation, ReactionType, ReactionDirection

builder = Builder(name="toy")

### Add general information to the model (stored in the ODS sheet named 'Info')
builder.add_info(category="General", key="Name", content="toy")
builder.add_info(category="General", key="Description", content="Toy model")

### Create and add the proteins used by the enzymes in the model (one protein per enzyme):
### - Protein masses are given in Da.
p1 = Protein(id="p1", mass=1000000.0)
p2 = Protein(id="p2", mass=1000000.0)
builder.add_proteins([p1, p2])

### Create and add the metabolites used in the model:
### - x_G is external glucose
### - G is internal glucose
### - Protein is a generic protein product
### - Metabolite masses are given in Da
x_G     = Metabolite(id="x_G", species_location=SpeciesLocation.EXTERNAL, mass=180.0)
G       = Metabolite(id="G", species_location=SpeciesLocation.INTERNAL, mass=180.0)
Protein = Metabolite(id="Protein", species_location=SpeciesLocation.INTERNAL,mass=180.0)
builder.add_metabolites([x_G, G, Protein])

### Create a transport reaction that imports glucose into the cell:
### - The enzyme is composed of one protein p1
### - The reaction is irreversible
### - kcat values are given in 1/h
### - KM values are given in g/L
rxn1 = Reaction(id="rxn1", lb=0.0, ub=1000.0,
                reaction_type=ReactionType.TRANSPORT,
                metabolites={"x_G":-1.0, "G": 1.0},
                proteins={"p1": 1.0})
rxn1.add_kcat_value(direction=ReactionDirection.FORWARD, kcat_value=45000.0)
rxn1.add_km_value(metabolite_id="x_G", km_value=0.00013)
rxn1.complete(kcat_value=0.0, km_value=0.0)
builder.add_reaction(rxn1)

### Create a ribosome-like reaction that uses internal glucose to produce protein:
### - The enzyme is composed of one protein p2
### - The reaction is irreversible
ribosome = Reaction(id="Ribosome", lb=0.0, ub=1000.0,
                    reaction_type=ReactionType.METABOLIC,
                    metabolites={"G":-1.0, "Protein": 1.0},
                    proteins={"p2": 1.0})
ribosome.add_kcat_value(direction=ReactionDirection.FORWARD, kcat_value=45000.0)
ribosome.add_km_value(metabolite_id="G", km_value=0.00013)
ribosome.complete(kcat_value=0.0, km_value=0.0)
builder.add_reaction(ribosome)

### Convert the model quantities to the GBA formalism (see Dourado et al. 2023)
builder.convert(ribosome_mass_kcat=4.55, ribosome_mass_km=8.3)
builder.build_GBA_model()

### Set the total cell density in g/L (here, the dry weight density)
builder.set_rho(340.0)

### Create a series of external conditions with decreasing external glucose concentration (g/L)
x_G_conc = 1.0
for i in range(25):
    builder.add_condition(condition_id=str(i+1), metabolites={"x_G": x_G_conc})
    x_G_conc *= 2/3

### Export the model to an ODS file
builder.export_to_ods()

In the second step, the exported ODS file is loaded back as a Model object so that numerical computations can be performed. The workflow first finds a feasible initial state, then solves the optimization problem for each glucose concentration.

from gba import read_ods_model

### Load the ODS model file created in the previous step
model = read_ods_model(name="toy")

### Find an initial feasible solution before running the optimization
model.find_initial_solution()

### Compute the optimal solution for each external condition
model.find_optimum_by_condition()

### Plot the growth rate mu as a function of external glucose concentration x_G
model.plot(x="x_G", y="mu", title="Growth rate", logx=True)

### Export the optimization results to a CSV file
model.export_optimization_data()

The final figure shows the predicted growth rate as a function of external glucose concentration.

Reference files

• 🔗 Toy model tutorial,
• 🔗 ODS file,
• 🔗 CSV optimization data.

Installation

The easiest way to install gbapy is from PyPI:

pip install gba

[!IMPORTANT] gbacpp software is required to run optimization tasks.

Supported platforms

gbapy has been primilary developed for Unix/Linux and macOS systems.

Dependencies

• Software

• gbacpp is required to run optimization tasks.

• Licensed Python modules

• The Python API of GUROBI optimizer must be installed and requires a user license (free for academics).

• Other Python modules

• NumPy
• pandas
• IPython
• plotly
• cobrapy
• molmass
• Biopython

Manual installation

If you want to install gbapy manually, download the latest release, and save it to a directory of your choice. Open a terminal, navigate to the gbapy/ directory and run:

sh install.sh

[!TIP] You can later uninstall the module using sh uninstall.sh.

Documentation

Documentation coming soon ...

Contributing

If you wish to contribute, do not hesitate to reach the developer.

Copyright

Copyright © 2024-2026 Charles Rocabert, Furkan Mert, Jérémie Muller-Prokob.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.