Biomass (Python)#

raven-toolbox objects in raven_toolbox.biomass.

Functions#

Function	Summary
`BiomassComponent`	One component of the biomass equation (protein, carbohydrate, and so on).
`BiomassConfig`	Container for the per-organism biomass layout.
`fit_parameters`	Fit stoichiometric parameters against experimental flux data.
`FitParametersResult`	Result of a `fit_parameters` call.
`ParameterPosition`	The model coefficients that one fitted parameter sets.
`rescale_pseudoreaction`	Multiply the substrate coefficients of one component pseudoreaction
`scale_biomass`	Rescale a component to a new mass fraction and optionally rescale a
`set_gam`	Set GAM (and optionally NGAM) on a model in place.
`sum_biomass`	Return the mass fraction (g/gDW) of each biomass component and the total.

Reference#

BiomassComponent#

One component of the biomass equation (protein, carbohydrate, and so on).

Attributes

name: Short name of the component. It is also the model.metabolites name of the metabolite that the pseudoreaction produces, which rescale_pseudoreaction uses to identify the product.
pseudoreaction_name: model.reactions[*].name of the pseudoreaction. The reaction is looked up by name, not by id, following the yeast-GEM naming convention.
mass_strategy: How to convert the pseudoreaction's substrates into a mass fraction. MassStrategy lists the choices and their offsets.

BiomassConfig#

Container for the per-organism biomass layout.

Attributes

biomass_rxn: model.reactions[*].id of the top-level biomass pseudoreaction (the one whose flux is the growth rate).
proton_met: model.metabolites[*].id of the cytosolic H+ metabolite. rescale_pseudoreaction sets its coefficient so that each pseudoreaction is charge-balanced after rescaling.
components: Ordered tuple of BiomassComponent describing every non-top-level pseudoreaction that contributes to mass.

fit_parameters#

fit_parameters(model: cobra.Model, x_rxns: Sequence[str], x_values: np.ndarray, rxns_to_fit: Sequence[str], values_to_fit: np.ndarray, parameter_positions: Sequence[ParameterPosition], *, fit_to_ratio: bool=True, initial_guess: Sequence[float] | None=None)

Fit stoichiometric parameters against experimental flux data.

Parameters

model:: Model to fit against. It is not modified; the fitted model is returned in the result.
x_rxns:: Ids of the reactions whose lower and upper bounds are fixed to a measured value at each data point.
x_values:: Measured values for x_rxns, shaped as the number of data points by len(x_rxns), columns in x_rxns order.
rxns_to_fit:: Ids of the reactions whose predicted flux is compared against measurements.
values_to_fit:: Measured values for rxns_to_fit, shaped data points × len(rxns_to_fit), columns in rxns_to_fit order.
parameter_positions:: One ParameterPosition per fitted parameter.
fit_to_ratio:: When True (default), the residual is the predicted flux divided by the measured value minus 1. When False, it is the predicted minus the measured flux.
initial_guess:: Starting value for each parameter (default 1 for every parameter).

Returns

FitParametersResult :

FitParametersResult#

Result of a fit_parameters call.

Parameters

parameters:: Fitted parameter magnitudes, same order as parameter_positions. Always non-negative; the sign of each coefficient comes from ParameterPosition.negative.
fitness_score:: The residual sum of squares at the fitted parameters.
success:: Whether the optimiser reports convergence (scipy.optimize.OptimizeResult.success). RAVEN's exitFlag (the fminsearch codes 1, 0 and -1) has no counterpart.
model:: Copy of the input model with the fitted parameters applied.
resulting_fluxes:: Flux of the fitted model at rxns_to_fit, one row per data point and one column per reaction in rxns_to_fit order.

ParameterPosition#

The model coefficients that one fitted parameter sets.

Attributes

entries:: (reaction_id, metabolite_id) pairs whose coefficient is set from this parameter.
negative:: Per entry, whether the coefficient is -parameter (consumption) or +parameter (production). Same length and order as entries.

rescale_pseudoreaction#

rescale_pseudoreaction(model: cobra.Model, config: BiomassConfig, component_name: str, factor: float)

Multiply the substrate coefficients of one component pseudoreaction

by factor and rebalance H+ to preserve charge neutrality.

Ports rescalePseudoReaction.m. A substrate is any metabolite whose name differs from the component's product name; the component's own metabolite (for example protein for the protein pseudoreaction) keeps its coefficient. After the rescaling the coefficient of config.proton_met is recomputed so that the total ionic charge of the reaction is zero.

Parameters

model : cobra.Model: Model that holds the pseudoreaction. It is modified in place.
config : BiomassConfig: Biomass components and the id of the proton metabolite (config.proton_met).
component_name : str: Name of the component in config whose pseudoreaction is rescaled. A name that is not in config raises KeyError.
factor : float: Multiplier for the coefficients of the substrates. A factor of 1 leaves the substrate coefficients unchanged, and the proton coefficient is still recomputed.

Raises

ValueError: If a metabolite of the reaction other than the proton has no charge (charge is None), because the charge balance is then unknown. Nothing is changed in that case.
KeyError: If the pseudoreaction or the proton metabolite is not in the model.

scale_biomass#

scale_biomass(model: cobra.Model, config: BiomassConfig, component_name: str, new_value: float, *, balance_out: str | None=None, target_total: float=1.0)

Rescale a component to a new mass fraction and optionally rescale a

second component so that the biomass total becomes target_total g/gDW.

Ports scaleBioMass.m. The rescaling factor is derived from sum_biomass on the current state of model, which is modified in place.

A ValueError is raised, before the model is changed, when the current fraction of the component or of balance_out is 0, or when the fraction of balance_out would become 0 or negative. Both rescalings are first applied to a scratch copy of the pseudoreactions, so an error leaves the model unchanged. The H+ rebalance adds to the fractions, so they are not linear in the scaling factor.

Parameters

model : cobra.Model: Model that holds the biomass pseudoreactions. It is modified in place.
config : BiomassConfig: Biomass components, their pseudoreaction names and the proton metabolite id.
component_name : str: Name of the component to rescale. A name that is not in config raises KeyError.
new_value : float: Target mass fraction of the component in g/gDW.
balance_out : str or None: Name of a second component that is rescaled so the components sum to target_total g/gDW, whatever the total was before. The sum equals target_total when the rescaled pseudoreaction needs no change of its H+ coefficient; otherwise the H+ rebalance adds to its fraction and the total exceeds target_total by that amount. Default None, which rescales only component_name.
target_total : float: Total mass fraction in g/gDW that balance_out aims for. Default 1.0. It has no effect when balance_out is None.

set_gam#

set_gam(model: cobra.Model, value: float, *, biomass_rxn: str, cofactor_met_names: Iterable[str], ngam_rxn: str | None=None, ngam_value: float | None=None)

Set GAM (and optionally NGAM) on a model in place.

Scales every metabolite participating in the biomass pseudoreaction whose name is in cofactor_met_names (for example ATP, ADP, H2O, H+, phosphate) to ±value, keeping the sign of its current coefficient.

If both ngam_rxn and ngam_value are given, the NGAM reaction's bounds are fixed at (ngam_value, ngam_value). An empty ngam_rxn counts as not given, and ngam_value without an ngam_rxn is an error. A given ngam_rxn must be in the model, also when no ngam_value is given.

Parameters

model: cobra model to mutate.
value: New GAM value (mmol ATP / gDW per growth unit).
biomass_rxn: Reaction id of the biomass pseudoreaction whose stoichiometry carries the GAM coefficients.
cofactor_met_names: Iterable of metabolite names (not ids). Every metabolite in the biomass pseudoreaction whose name is in this set is rescaled. yeast-GEM uses {"ATP", "ADP", "H2O", "H+", "phosphate"}.
ngam_rxn, ngam_value: Optional NGAM update. If both are provided, the reaction's bounds are set to (ngam_value, ngam_value) (equality constraint).

Returns

cobra.Model: The modified model (the input object).

Raises

KeyError: If biomass_rxn, or a given ngam_rxn, is not in the model. Both reactions are looked up before anything is changed.
ValueError: If ngam_value is given without an ngam_rxn.

sum_biomass#

sum_biomass(model: cobra.Model, config: BiomassConfig)

Return the mass fraction (g/gDW) of each biomass component and the total.

Mirrors yeast-GEM's sumBioMass.m. The dict has one key per BiomassComponent name and the key "total". Components whose pseudoreaction is missing from the model contribute 0.

Parameters

model : cobra.Model: Model that holds the biomass pseudoreactions. It is not modified.
config : BiomassConfig: Biomass components, their pseudoreaction names and their mass strategies.

Raises

ValueError: If a substrate of a component whose mass strategy is not "grams" has an empty formula or a formula with an element missing from the atomic-weight table.