10. API

CommunityModel

class dcFBA.Models.CommunityModel(models: list[cbmpy.CBModel.Model], biomass_reaction_ids: list[str], ids: list[str] = [], combined_model_id: str = 'combined_model')

Bases: Model

A CommunityModel represents a combined model built from multiple individual models to simulate a community of organisms.

m_identifiers

List of user-specified identifiers for the individual models.

Type:

list[str]

m_single_model_ids

List of IDs of the individual models.

Type:

list[str]

m_single_model_biomass_reaction_ids

List of biomass reaction IDs of the individual models.

Type:

list[str]

add_model_to_community(model: Model, biomass_reaction: str, new_id: str | None = None) → None

Adds a model to the CommunityModel.

Parameters:

  • model (Model) – The model to be added.

  • biomass_reaction (str) – The reaction ID of the biomass reaction of the new model.

  • new_id (str, optional) – The user-set identifier for the model. Defaults to None. If set to None, the model ID will be used.

clone()

Create a deep copy of the CommunityModel instance.

Returns:

A new deep copy of the CommunityModel instance.

Return type:

CommunityModel

get_model_specific_reactions(mid: str) → list[str]

Returns a list of reaction IDs specific to the given model.

Parameters:

mid (str) – The identifier of the model.

Raises:

  • NotInCombinedModel – If the provided model ID is not in the

  • CommunityModel. –

Returns:

A list of reaction IDs specific to the given model.

Return type:

list[Reaction]

get_model_specific_species(mid: str) → list[str]

Returns a list of species IDs specific to the given model.

Parameters:

mid (str) – The identifier of the model.

Raises:

  • NotInCombinedModel – If the provided model ID is not in the

  • CommunityModel. –

Returns:

A list of species IDs specific to the given model.

Return type:

list[Species]

get_reaction_bigg_ids(mid='') → list[str]

Get the reaction BIGG IDs of all reactions

Parameters:

  • mid (str, optional) – If a model id is provided only reactions from

  • returned (the specific model are) –

  • "". (Defaults to) –

Raises:

NotInCombinedModel – the id provided was not in the combined model

Returns:

list containing the BIGG ids

Return type:

list[str]

get_species_bigg_ids(mid='') → list[str]

Get the species bigg ids of all species

Parameters:

  • mid (str, optional) – When provided only the ids of a specific

  • returned. (model are) –

  • "". (Defaults to) –

Raises:

NotInCombinedModel – the id provided was not in the combined model

Returns:

list containing the bigg ids

Return type:

list[str]

identify_biomass_reaction_for_model(mid: str) → list[str]

Given a model id return the biomass reaction

Parameters:

mid (str) – _description_

Returns:

_description_

Return type:

str

identify_model_from_reaction(rid: str) → str

Given a reaction id get the single model this reaction belonged to

Parameters:

rid (str) – reaction id of the kinetic model

Returns:

id of the old model

Return type:

str

remove_model_from_community(mid: str) → None

Remove a model from the CommunityModel.

Parameters:

mid (str) – The identifier of the model to be removed.

Raises:

Exception – If the provided model ID is not in the CommunityModel.

DynamicModelBase

class dcFBA.DynamicModels.DynamicModelBase.DynamicModelBase

Bases: object

Base class for the Dynamic FBA (Flux Balance Analysis) models.

_biomasses

Dictionary containing biomass concentrations.

Type:

dict

_metabolites

Dictionary containing metabolite concentrations.

Type:

dict

_fluxes

Dictionary containing flux values.

Type:

dict

_times

List of time points used in the simulation.

Type:

list

_kinetics

Structure holding kinetic information.

Type:

KineticsStruct

property biomasses

Get the biomasses dictionary.

property fluxes

Get the fluxes dictionary.

get_biomasses()

Return the biomasses dictionary.

Returns:

Dictionary containing biomass information.

Return type:

dict

get_community_growth_rate() → list[float]

Get the community growth rate over time.

Returns:

Community growth rate values over time.

Return type:

list[float]

get_fluxes()

Return the fluxes dictionary.

Returns:

Dictionary containing flux information.

Return type:

dict

get_fluxes_values() → dict[str, float]

Get the flux values for each time point given a reaction ID.

Returns:

Dictionary of flux values for each time point.

Return type:

dict[str, float]

get_metabolites()

Return the metabolites dictionary.

Returns:

Dictionary containing metabolite information.

Return type:

dict

get_relative_abundance()

Get the percentage of each species for each time point.

Returns:

list containing the relative abundance of each species for each time point.

Return type:

list[float]

get_specific_flux_values() → list[float]

Get specific flux values.

Returns:

Specific flux values.

Return type:

list[float]

get_time_points() → list

Return the list of time points for the simulation.

Returns:

List of time points.

Return type:

list

property kinetics: KineticsStruct

Get the kinetic information.

property metabolites

Get the metabolites dictionary.

property times

Get the list of time-points used

EndPointFBA

class dcFBA.DynamicModels.EndPointFBA.EndPointFBA(community_model: CommunityModel, n: int, initial_biomasses: dict[str, float], initial_concentrations: dict[str, float] = {}, dt: float = 0.1, kinetics: KineticsStruct | None = None)

Bases: DynamicModelBase

EndPointFBA class

This class provides the blueprint and functionality to perform EndPointFBA on a CommunityModel. Inherits from the DynamicModelBase class.

balanced_growth(Xin: float, Xm: float) → None

Set balanced growth constraint

Parameters:

  • Xin (float) – Total community biomass at the first time point

  • Xm (float) – Total community biomass at the final time point

constrain_rates(epsilon=0.1)

Constrains the difference in reaction rates between t_n-1 and t_n.

See the docs for further explanation

Parameters:

epsilon (float, optional) – Maximum allowed rate difference between successive time points. Defaults to 0.1.

property dt: float

Returns the size of the time step.

get_community_growth_rate() → list[float]

Calculates and returns the community growth rate over time.”

Returns:

Community growth rate

Return type:

list[float]

get_flux_values(rid: str) → list[float]

Returns the flux values for each time point given a reaction ID.

Parameters:

rid (str) – Reaction id of the original model

Returns:

aggregated flux values for each time point

Return type:

list[float]

get_fluxes_values(rids: list[str]) → dict[str, list[float]]

Returns the flux values for a list of reaction IDs for each time point.

Parameters:

rids (list[str]) – List of reaction ids for which you want the flux vales

Returns:

dictionary containing reaction id

and the flux values foreach time-point

Return type:

dict[str, list[float]]

get_relative_abundance() → dict[str, list[float]]

Calculates and returns the relative abundance, or percentage of each species in the community for each time point.

Returns:

model_id : relative abundance over time

Return type:

dict[str, list[float]]

get_specific_flux_values(rid: str) → list[float]

Returns specific flux values for a given reaction ID. Specific flux is defined by the aggregated flux divided by the time-step size times the biomass

Parameters:

rid (str) – reaction id of the original model

Returns:

specific flux values

Return type:

list[float]

mm_approximation(rid: str)

Approximates the Michaelis-Menten curve for a given reaction using two linear lines.

When the EndPointFBA model is initialized with a KineticsStruct object, this method approximates the Michaelis-Menten (MM) kinetics of a given reaction by using two linear lines instead of directly setting an upper and lower bound.

See official documentation for a comprehensive explanation of this approximation method.

Parameters:

rid (str) – The reaction ID for which the MM approximation is to be applied.

Raises:

Exception – If no limiting substrate is defined in the kinetics object for the specified reaction.

property model: CommunityModel

Returns the community model used in the simulation.

remove_balanced_growth_constraints(initial_biomasses={})
Restore the EndPointFBA model to before balanced growth constraints

were added

Parameters:

initial_biomasses (dict, optional) – _description_. Defaults to {}.

set_qp(solution: float, epsilon=0.0) → None

Sets the quadratic objective to minimize all consecutive fluxes.

Parameters:

solution (float) –

Solution for the final X_comm flux

epsilon (float, optional): How much the solution can differ from

the final amount of biomass. Defaults to 0.01.

set_subset_qp(solution: float, reactions: list[str], epsilon=0.0) → None

QP for specified reaction ids

Parameters:

  • solution (float) – Solution for the final X_comm flux

  • reactions (list[str]) – Reactions for which the consecutive fluxes are minimized

  • epsilon (float, optional) – How much the solution can differ from the final amount of biomass. Defaults to 0.01.

simulate(sparse=False) → float

Performs FBA (Flux Balance Analysis) on the EndPointFBA matrix.

Parameters:

sparse – Set to true if you want to use a sparse matrix Sparse matrix decreases the amount of memory required

StaticOptimizationModel

class dcFBA.DynamicModels.StaticOptimizationModel.StaticOptimizationModelBase

Bases: DynamicModelBase

Base class providing a framework for the static optimization approaches (SOA) Base class for methods using time steps to track biomass and metabolite concentrations over time.

_initial_bounds

Containing the original upper and lower bound for all reactions

Type:

dict

check_solution_feasibility() → str

Checks if the current solution has any metabolite concentration below zero.

Returns:

The species ID with the lowest negative concentration,

or an empty string if all concentrations are positive.

Return type:

str

importers_species_concentration(rid: str, transporters: Transporters) → list[float]

Given an importer reaction, returns the species concentrations that this importer imports.

Parameters:

  • rid (str) – The reaction id of the importer.

  • transporters (Transporters) – A Transporters object.

Returns:

List of species concentrations.

Return type:

list[float]

mm_kinetics(reaction: Reaction, X: float, kinetics: KineticsStruct) → None

Computes the Michaelis-Menten kinetics for a given reaction.

If the reaction is an importer and no limiting substrate was provided, the function uses the minimum concentration of all substrates.

Args:

reaction (Reaction): A reaction object. X (float): The biomass of the species the reaction belongs to. transporters (Transporters): A Transporters object of the model. kinetics (Kinetics): A Kinetics object for kinetic parameter retrieval.

Raises:

  • NoLimitingSubstrateFound – Raised if the reaction isn’t an import reaction and

  • no limiting substrate was provided or if the provided substrate isn't external. –

simulate(dt: float, n: int = 10000, epsilon=0.001, kinetics_func=None, deviate=None)

Placeholder for dynamic FBA simulation over specified time intervals. This method should be overridden in subclasses to implement specific simulation logic.

Parameters:

  • dt (float) – The time step for simulation.

  • n (int, optional) – number of simulation Defaults to 10000

  • epsilon (float, optional) – The tolerance value. When the solution or time step is less than epsilon, the simulation stops. Defaults to 0.001.

  • kinetics_func (function, optional) – A user-defined function to calculate kinetics. Defaults to None.

  • deviate (function, optional) – A function to apply model changes during the simulation. Should accept: the model, biomass concentrations, metabolite concentrations, and dt as parameters. Defaults to None.

update_biomasses() → None

Update all biomass concentration

update_concentrations() → None

Update all metabolite concentrations

update_exchanges(dt: float) → None

Updates the lower and upper bound of the exchange reaction, according to the amount of external metabolite present

Parameters:

dt (float) – time step size

update_reaction_bounds(kinetics_func) → None

Updates all reaction bounds using the new concentrations.

Parameters:

kinetics_func (function) – A user-defined function that calculates the new upper bound for a reaction. It should accept: - cbmpy.CBModel, a string (reaction_id), - dictionary of biomass concentrations, - a dictionary of metabolite concentrations.

DynamicFBABase

class dcFBA.DynamicModels.DynamicFBABase.DynamicFBABase(model: ~dcFBA.Models.CommunityModel.CommunityModel, biomasses: list[float], initial_concentrations: dict[str, float] = {}, kinetics: ~dcFBA.Models.KineticsStruct.KineticsStruct = <dcFBA.Models.KineticsStruct.KineticsStruct object>)

Bases: StaticOptimizationModelBase

Base class for SingleDynamicFBA and JointFBA.

Implements the core code for simulating both models. The distinction between the two is the presence of a Community Biomass in Dynamic JointFBA.

get_flux_values(rid: str) → list[float]

Get the flux values for a specific reaction over time.

Parameters:

rid (str) – The reaction ID.

Returns:

List of flux values for the specified reaction over time.

Return type:

list[float]

get_fluxes_values(rids: list[str]) → dict[str, list[float]]

Get the flux values for multiple reactions over time.

Parameters:

rids (list[str]) – List of reaction IDs.

Returns:

Dictionary mapping reaction IDs to lists of flux values over time.

Return type:

dict[str, list[float]]

get_specific_flux_values(rid: str) → list[float]

Get the specific flux values for a given reaction.

Parameters:

rid (str) – The reaction ID.

Returns:

List of specific flux values for the specified

reaction over time. Returns an empty list if the reaction is an exchange reaction.

Return type:

list[float]

simulate(dt: float, n: int = 10000, epsilon=1e-06, kinetics_func=None, deviate=None) → None

Perform a dynamic joint FBA simulation.

update_concentrations(FBAsol: dict[str, float], dt: float) → None

Update metabolite concentrations after an FBA simulation step.

Parameters:

  • FBAsol (dict) – The solution vector from the FBA.

  • dt (float) – The time step for the simulation.

update_exchanges(dt: float) → None

Update exchange reaction lower bounds based on the metabolite concentration of the current time step.

Parameters:

dt (float) – The time step for the simulation.

update_reaction_bounds(kinetics_func) → None

Update the reaction bounds for the simulation based on either provided kinetics or standard bounds.

Parameters:

kinetics_func (function) – A custom function to adjust reaction bounds based on kinetics. Uses standard bounds if None.

DynamicSingleFBA

class dcFBA.DynamicModels.DynamicSingleFBA.DynamicSingleFBA(model: ~cbmpy.CBModel.Model, biomass_id: str, initial_biomass: float, initial_concentrations: dict[str, float] = {}, kinetics: ~dcFBA.Models.KineticsStruct.KineticsStruct = <dcFBA.Models.KineticsStruct.KineticsStruct object>)

Bases: DynamicFBABase

DynamicSingleFBA Class.

This class provides functionality to perform a dynamic Flux Balance Analysis (FBA) on a single model. It inherits from the DynamicFBABase and internally converts the single model to a community model representation for consistent handling of dynamic simulations.

get_biomass() → list[float]

Get the total biomass over time

Returns:

Biomass concentration over time

Return type:

list[float]

DynamicJointFba

class dcFBA.DynamicModels.DynamicJointFBA.DynamicJointFBA(model: ~dcFBA.Models.CommunityModel.CommunityModel, biomasses: list[float], initial_concentrations: dict[str, float] = {}, kinetics: ~dcFBA.Models.KineticsStruct.KineticsStruct = <dcFBA.Models.KineticsStruct.KineticsStruct object>)

Bases: DynamicFBABase

A class to perform dynamic joint Flux Balance Analysis (FBA) on a community model.

This class facilitates dynamic joint FBA simulations by providing methods to set up and manage the community model, including the creation and management of community biomass reactions.

m_model

The community metabolic model being simulated.

Type:

CommunityModel

m_initial_bounds

Initial bounds for the model reactions. Defaults to an empty dictionary.

Type:

dict[str, tuple[float, float]], optional

get_community_growth_rate() → list[float]

Calculates and returns the community growth rate

Returns:

community growth rate over time

Return type:

list[float]

get_relative_abundance() → dict[str, list[float]]

Calculate the relative abundance for each species

Returns:

Model id followed by the relative

abundance over time

Return type:

dict[str, list[float]]

set_community_biomass_reaction() → None

Set up the community biomass reaction.

This method establishes the community biomass species ‘X_c’ and associates it with each model’s biomass reaction. Additionally, a community biomass exchange reaction (X_comm) is created and designated as the model’s objective function.

DynamicParallelFBA

class dcFBA.DynamicModels.DynamicParallelFBA.DynamicParallelFBA(models: list[cbmpy.CBModel.Model], biomasses: list[float], initial_concentrations: dict[str, float] = {}, kinetics: dict[str, dcFBA.Models.KineticsStruct.KineticsStruct] = {})

Bases: StaticOptimizationModelBase

A class representing a dynamic parallel FBA simulation.

This class extends the StaticOptimizationModelBase and provides functionality for performing dynamic FBA simulations on multiple models in parallel. .. attribute:: models

The models in the parallel system

type:

list[cbmpy.CBModel.Model]

get_community_growth_rate()

Get the community growth rate over time.

Returns:

Community growth rate values over time.

Return type:

list[float]

get_flux_values(mid: str, rid: str) → list[float]

Returns the aggregated flux values for each time point given a reaction ID.

Parameters:

  • mid (str) – The model id of the reaction

  • rid (str) – The reaction id

Returns:

the flux value for each time point

Return type:

list[float]

get_fluxes_values(mid: str, rids: list[str]) → dict[str, float]

Get the aggregated flux values for multiple reactions

Parameters:

  • mid (str) – The model id of the reaction

  • rids (list[str]) – The reactions of interest

Returns:

Dictionary contain a reaction id and flux values

for each time point

Return type:

dict[str, float]

get_relative_abundance() → dict[str, list[float]]

Get the percentage of each species for each time point.

Returns:

list containing the relative abundance of each species for each time point.

Return type:

list[float]

get_specific_flux_values(mid: str, rid: str) → list[float]

Calculated and return the specific flux values

Parameters:

  • mid (str) – Model id for the reaction

  • rid (str) – reaciton id

Returns:

List of specific flux values for each time point

Return type:

list[float]

reset_dt(species_id, FBAsol) → float

Recompute a smaller time step if the obtained result was infeasible.

Parameters:

  • species_id (str) – ID of the species for which the time step is recalculated.

  • FBAsol (dict) – Solution vector from the FBA.

Returns:

Adjusted time step.

Return type:

float

simulate(dt: float, n: int = 10000, epsilon: float = 1e-06, kinetics_func=None, deviate=None) → None

Placeholder for dynamic FBA simulation over specified time intervals. This method should be overridden in subclasses to implement specific simulation logic.

Parameters:

  • dt (float) – The time step for simulation.

  • n (int, optional) – number of simulation Defaults to 10000

  • epsilon (float, optional) – The tolerance value. When the solution or time step is less than epsilon, the simulation stops. Defaults to 0.001.

  • kinetics_func (function, optional) – A user-defined function to calculate kinetics. Defaults to None.

  • deviate (function, optional) – A function to apply model changes during the simulation. Should accept: the model, biomass concentrations, metabolite concentrations, and dt as parameters. Defaults to None.

update_biomasses(fluxes: dict[str, dict[str, float]], dt: float) → None

Modify biomass concentrations after completing an FBA step.

Parameters:

  • fluxes (dict[str, dict[str, float]]) – FBA result

  • dt (float) – time step size

update_concentrations(fluxes: dict[str, dict[str, float]], dt: float) → None

Update the concentrations according to the calculated fluxes

Parameters:

  • fluxes (dict[str, dict[str, float]]) – FBA solution

  • dt (float) – time step

update_exchanges(dt)

Adjust exchange reactions based on the present metabolite concentrations.

Parameters:

dt (float) – time step size

update_reaction_bounds(kinetics_func) → None

Update the reaction bounds for all models.

Parameters:

kinetics_func (function) – Custom function to modify reaction bounds based on kinetic data.

KineticStruct

class dcFBA.Models.KineticsStruct.KineticsStruct(kinetics: dict[str, tuple[str, float, float]] = {})

Bases: object

This class represents a collection of reaction kinetics data. It stores the kinetics information as a dictionary, where the reaction identifier (rid) is the key, and the associated tuple of vmax and km values is the value.

kinetics reaction_id => tuple(limiting_species_id, km, vmax)

Usage:

  • Add kinetics data for a reaction using the Add() method.

  • Remove kinetics data for a reaction using the Remove() method.

  • Check if kinetics data exists for a reaction using the Exists() method.

  • Retrieve km value for a reaction using the get_km() method.

  • Retrieve vmax value for a reaction using the get_vmax() method.

  • Retrieve the tuple of vmax and km values for a reaction using the get_kinetics() method.

exists(rid: str) → bool

Checks if kinetic data is available for reaction

Parameters:

rid (str) – _description_

Returns:

_description_

Return type:

bool

OptimalSearch

dcFBA.Helpers.OptimalSearch.balanced_search_quick(ep: EndPointFBA, X_initial, objective, epsilon=0.01)

Run this one if you know what you are doing, quick and dirty solution

Finds the lowest number of time points given initial values and a dt

Parameters:

  • cm (CommunityModel) – _description_

  • initial_biomasses (dict[str, float]) – _description_

  • initial_concentrations (dict[str, float], optional) – _description_. Defaults to {}.

  • dt (float, optional) – _description_. Defaults to 0.1.

  • set_values (tuple[float, float], optional) – Set to identify when a specific value is attained. [value, N]. Where value is the value you want to reach and N the initial guess of N. Defaults to None

Returns:

number of time points and the reached objective

value

Return type:

ist[float, float]

ReduceModel

Helper function which loops over all reactions in a Model or CommunityModel. Sets the reaction as the objective function and checks, given a medium if the reaction can take place

dcFBA.Helpers.ReduceModel.reduce_model(model: Model, medium: dict[str, float]) → None

Remove unused reactions and metabolites from the model

dcFBA.Helpers.ReduceModel.scan_unused_reactions(model: Model, medium: dict[str, float]) → list[str]

Generate list of unused reactions

Parameters:

  • model (Model) – a GSMM

  • medium (dict[str, float]) – The medium the model is in

Returns:

All the unused reactions given the medium

Return type:

list[str]