Biomass (Python)

raven-toolbox objects in raven_toolbox.biomass.

Functions

Function	Summary
BiomassComponent	One component of the biomass equation (protein, carbohydrate, …).
BiomassConfig	Container for the per-organism biomass layout.
fit_parameters	Fit stoichiometric parameters against experimental flux data.
FitParametersResult	Outcome of a fit_parameters call.
ParameterPosition	Where one fitted parameter's coefficient goes in the model.
rescale_pseudoreaction	Multiply the substrate coefficients of one component pseudoreaction
scale_biomass	Rescale a component to a new mass fraction, optionally balancing
set_gam	Set GAM (and optionally NGAM) on a model in place.
sum_biomass	Mass-fraction (g/gDW) per biomass component plus the total.

Reference

BiomassComponent

One component of the biomass equation (protein, carbohydrate, …).

Attributes

name

Canonical short name — also the model.metabolites name of the metabolite that the pseudoreaction produces. Used by rescale_pseudoreaction to identify the product side.

pseudoreaction_name

model.reactions[*].name of the pseudoreaction. cobrapy reactions are looked up by name (not id) because that is how the yeast-GEM convention names them.

mass_strategy

How to convert the pseudoreaction's substrates into a mass fraction. See MassStrategy for 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 — used by rescale_pseudoreaction to keep each pseudoreaction 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. Never modified — the fitted model is returned separately.

x_rxns:

Ids of the reactions that get fixed (both bounds) to a measured value at each data point.

x_values:

Measured values for x_rxns, shaped data points × 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:

Fit the ratio of predicted to measured value instead of the absolute difference, so a large flux does not dominate the residual sum of squares just by being large (default True).

initial_guess:

Starting value for each parameter (default all ones).

Returns

FitParametersResult :

FitParametersResult

Outcome of a fit_parameters call.

Parameters

parameters:

Fitted parameter magnitudes, same order as parameter_positions. Always non-negative — sign is carried entirely by ParameterPosition.negative.

fitness_score:

The residual sum of squares at the fitted parameters.

success:

Whether the optimizer reports convergence (scipy.optimize.OptimizeResult.success). RAVEN's own exitFlag (fminsearch's 1/0/-1 codes) has no equivalent worth carrying over: different optimizer, different convergence bookkeeping.

model:

Copy of the input model with the fitted parameters applied.

resulting_fluxes:

The fitted model's own predicted flux at rxns_to_fit, one row per data point, columns in rxns_to_fit order — what a caller would plot against values_to_fit to see the fit.

ParameterPosition

Where one fitted parameter's coefficient goes in the model.

Attributes

entries:

(reaction_id, metabolite_id) pairs this parameter's magnitude is written to.

negative:

Per entry, whether that coefficient is -parameter rather than +parameter (to tell production from consumption at the same magnitude) — 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. "Substrate" here means any metabolite whose name is not the component's product name; the component's own metabolite (e.g. protein for the protein pseudoreaction) is left untouched. After the rescaling the coefficient of config.proton_met is recomputed so the reaction's total ionic charge sums to zero.

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, optionally balancing

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

Ports scaleBioMass.m. The rescaling factor is derived from sum_biomass on the current model state, so call this with an in-place model mutation, not on a stale snapshot.

With balance_out, that component is rescaled so the components sum to exactly target_total g/gDW (default 1), whatever the total was before. It must be large enough to absorb the difference: a ValueError is raised, before the model is changed, when its fraction is 0 or would become 0 or negative. target_total has no effect without balance_out.

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 (e.g. ATP, ADP, H2O, H+, phosphate) to ±value, preserving 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).

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 will be 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 (mutated) model, for chaining.

sum_biomass

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

Mass-fraction (g/gDW) per biomass component plus the total.

Mirrors yeast-GEM's sumBioMass.m. Returns a dict keyed by each BiomassComponent name plus "total". Components whose pseudoreaction is missing from the model contribute 0 (logged as a warning).