Utils Module

Documentation for the mimeco.utils module. This module contains functions that eventually allow the analysis from the mimeco.analysis module. They can be used to support personnalized model analysis.

Created on Fri Jan 17 10:37:38 2025

@author: e158401a

mimeco.utils.correlation(sampling)

Measures correlation between all reactions of the ecosystem model. Correlation type : spearman, because we are interested in common evolution, not proportionnality.

Parameters:: sampling (pandas.dataframe) – columns : reactions_id rows : string(objective-value-model1_objective-value-model2) for a given sample
Returns:: correlation_reactions – a correlation matrix featuring all reactions of the ecosystem model
Return type:: pandas dataframe

mimeco.utils.create_ecosystem_metabolic_dict(model1, model2)

Builds a dictionnary for how to name the metabolites of each inputted model in the ecosystem model. Here, we keep the same ids.

Parameters:

model1 (cobra.Model)
model2 (cobra.Model)

Returns:

metabolic_dict – Dictionnary of all metabolites of the inputted models, and how to name them in the ecosystem model.

Return type:

dictionnary {(met_id, model): met_id}

mimeco.utils.crossfed_mets(model1, sampling, correlation_reactions, model1_id, model2_id, model1_biomass_id, model2_biomass_id, exchange_correlation=0.5, biomass_correlation=0.8, lower_exchange_proportion=0.3)

Infers metabolites that are exchanged between organisms in the ecosystem models, correlated with an increasing model1 objective value. In other words, crossfed metabolite benefitting model1. Correlation options can be customized. Spearman correlation is used.

Parameters:

model1 (cobra.Model)
sampling (pandas.dataframe) – columns : reactions_id rows : string(objective-value-model1_objective-value-model2) for a given sample
correlation_reactions (pandas dataframe) – a correlation matrix featuring all reactions of the ecosystem model
model1_id (string) – Model denomination in the cobra.Model of model1
model2_id (string) – Model denomination in the cobra.Model of model2
model1_biomass_id (string) – id of the reaction used as objective in model1 (if the objective coefficient is not null for several reactions, then a new reaction must be built to constrain the model to a given objective value through its flux)
model2_biomass_id (string) – id of the reaction used as objective in model2 (if the objective coefficient is not null for several reactions, then a new reaction must be built to constrain the model to a given objective value through its flux)
exchange_correlation (float between 0 and -1, optional) – defines the level correlation between secretion and uptake of a same metabolite by paired models default is 0.5
biomass_correlation (float between 0 and 1, optional) – correlation between the exchange of the metabolite and the biomass production of model2 for its selection as crossfed.
lower_exchange_proportion (float between 0 and 1, optional) – proportion of the sampling solutions in which the metabolite of interest is secreted by one organism and uptaken by the other.

Returns:

potential_crossfeeding – columns : metabolite_id model_benefiting, proportion_exchange (proportion of samples featuring inverse secretion/uptake for a same metabolite), proportion_model1_to_model2 (proportion of samples with metabolite exchange from model1 to model2), proportion_model2_to_model1 (proportion of samples with metabolite exchange from model2 to model1), correlation_obj_model1, correlation_obj_model2

Return type:

pandas.dataframe

mimeco.utils.extract_sampling_data(model1, sampling, potential_crossfeeding, model1_id, model2_id)

Extracts sampling data from predicted exchanged metabolites, and models objective values for each sample.

Parameters:

sampling (pandas.dataframe) – columns : reactions_id rows : string(objective-value-model1_objective-value-model2) for a given sample
potential_crossfeeding (dictionnary) – keys : metabolites id values : [proportion of samples featuring inverse secretion/uptake for a same metabolite, proportion of samples with metabolite exchange from model1 to model2, proportion of samples with metabolite exchange from model2 to model1]
model1_id (string) – Model denomination in the cobra.Model of model1
model2_id (string) – Model denomination in the cobra.Model of model1

Returns:

sampling_data – Dataframe based on the sampling, resulting in each rw bing a sample. The first two columns records the objective value, in the given sample, of both models. Other columns are, by pairs, the flux values of the exchange reactions of a crossfed metabolite for both models.

Return type:

pandas dataframe

mimeco.utils.find_namespace(model): Identifies the namespace of the given model. Bigg (CarveMe), Agora (VMH) and gapseq namespace are tested and supported on mimeco. Other namespace could require adaptation.

mimeco.utils.infer_interaction_score(xy)

Calculates pareto front’s area under the curve to determine the interaction score of the ecosystem.

Parameters:

xy (pandas dataframe)
Normalized pareto points

Returns:

interaction_score – Predicts the nature of the interaction between model1 and model 2. Score < 0 predicts a competitive interaction, Score = 0 predicts a neutral interaction Score > 0 predicts a positive interaction

Return type:

float

mimeco.utils.infer_interaction_type(xy, interaction_score, maxi_model1, maxi_model2, solo_growth_model1, solo_growth_model2)

Infers inetraction type from the models solo maximal objective values, ecosystem maximal objective value and interaction score.

Parameters:

xy (pandas dataframe)
Normalized pareto points
interaction_score (float) – Predicts the nature of the interaction between model1 and model 2. Score < 0 predicts a competitive interaction, Score = 0 predicts a neutral interaction Score > 0 predicts a positive interaction
maxi_model1 (numpy.ndarray) – Pareto solution in which model1 objective value is the highest.
maxi_model2 (numpy.ndarray) – Pareto solution in which model2 objective value is the highest.
solo_growth_model1 (float) – Objective value of model1 when optimized alone in the described medium
solo_growth_model2 (float) – Objective value of model2 when optimized alone in the described medium

Returns:

interaction_type – Qualitative description (competition, neutrality, favors model1, favors model2, limited mutualism or mutualism) of the metabolic interaction between models

Return type:

string

mimeco.utils.mo_fba(model1, model2, metabolic_dict, constrained_medium_dict)

Compute multi-objective FBA between the two given models

Parameters:

model1 (cobra.Model)
model2 (cobra.Model)
metabolic_dict (dictionnary {(met_id, model): met_id}) – Dictionnary of all metabolites of the inputted models, and how to name them in the ecosystem model.
constrained_medium_dict (dictionnary {met_id:(lower_bound,upper_bound)}) – Guide constraint of the ecosystem medium based on inputted medium data. Controls fluxes of metabolites entering the emodels external environment.

Returns:

Multi-objective solution (Pareto front) of the ecosystem model

Return type:

sol_mofba

mimeco.utils.mocba_to_cobra(ecosys)

Converts the ecosystem model built through mocbapy to a cobra.Model

Parameters:: ecosys (mocbapy.EcosystemModel)
Returns:: cobra_model
Return type:: cobra.Model

mimeco.utils.no_compartment_id(metabolite)

Separates metabolic id from the compartment information. Aknowledges BiGG, AGORA and gapseq namespaces.

Parameters:

metabolite (cobra.Metabolite)

Returns:

metabolite (string) – metabolite_id, without its compartment information
suffixe (string) – compartment information of the inputted metabolite

mimeco.utils.oppositeSigns(x, y)

mimeco.utils.pareto_parsing(sol_mofba, solo_growth_model1, solo_growth_model2)

Parses the Pareto front and returns its points normalized by the optimal growth of each model optimized in isolation

Parameters:

sol_mofba – Multi-objective solution (Pareto front) of the ecosystem model
solo_growth_model1 (float) – Objective value of model1 when optimized alone in the described medium
solo_growth_model2 (float) – Objective value of model2 when optimized alone in the described medium

Returns:

xy (pandas dataframe)
Normalized pareto points
maxi_model1 (numpy.ndarray) – Pareto solution in which model1 objective value is the highest.
maxi_model2 (numpy.ndarray) – Pareto solution in which model2 objective value is the highest.

mimeco.utils.pareto_plot(xy, model1_id, model2_id)

mimeco.utils.pareto_sampling(cobra_ecosys, xy, solo_growth_model1, solo_growth_model2, model1_id, model2_id, model1_biomass_id, model2_biomass_id, sample_size=1000)

Samples the Pareto front, infering a solution for <sample_size> points on the pareto front.

Parameters:

cobra_ecosys (mocbapy.EcosystemModel)
xy (pandas dataframe)
Normalized pareto points
solo_growth_model1 (float) – Objective value of model1 when optimized alone in the described medium
solo_growth_model2 (float) – Objective value of model2 when optimized alone in the described medium
model1_id (string) – Model denomination in the cobra.Model of model1
model2_id (string) – Model denomination in the cobra.Model of model2
model1_biomass_id (string) – id of the reaction used as objective in model1 (if the objective coefficient is not null for several reactions, then a new reaction must be built to constrain the model to a given objective value through its flux)
model2_biomass_id (string) – id of the reaction used as objective in model2 (if the objective coefficient is not null for several reactions, hen a new reaction must be built to constrain the model to a given objective value through its flux)
sample_size (int, optional) – Number of samples sampled from the Pareto front to infer correlation between exchange reactions and biomass. Default is 1000.

Returns:

sampling – columns : reactions_id rows : string(objective-value-model1_objective-value-model2) for a given sample

Return type:

pandas.dataframe

mimeco.utils.plot_exchange(model1, sampling, potential_crossfeeding, model1_id, model2_id)

Visualizes crossfed metablites flux evlution on along the pareto front. This visualisation is rudimentary.

Parameters:

sampling (pandas.dataframe) – columns : reactions_id rows : string(objective-value-model1_objective-value-model2) for a given sample
potential_crossfeeding (dictionnary) – keys : metabolites id values : [proportion of samples featuring inverse secretion/uptake for a same metabolite, proportion of samples with metabolite exchange from model1 to model2, proportion of samples with metabolite exchange from model2 to model1]
model1_id (string) – Model denomination in the cobra.Model of model1
model2_id (string) – Model denomination in the cobra.Model of model1

mimeco.utils.reac_to_met_id(reac, model_id)

Returns exchanged metabolite id from an exchange reaction.

Parameters:

reac (cobra.Reaction.id)
model_id (string) – Model denomination in the cobra.Model

Returns:

met – metabolite id

Return type:

string

mimeco.utils.restrain_medium(model, medium, undescribed_metabolites_constraint, undescribed_met_lb=-0.1)

Builds the dictionnary used for constraining the medium of the ecosystem model based on inputted medium data.

Parameters:

model (cobra.Model)
medium (pandas series) – Index : metabolites names values : Availability of corresponding metabolite in the medium as a positive flux value.
undescribed_metabolites_constraint (string (“blocked”, “partially_constrained” or “as_is”).) – How strictly constrained are the medium metabolites for which the flux is not described in the medium dataframe. “blocked” : They are not available in the medium at all (can result in model unable to grow) “partially_constrained” : They are made available with an influx in the medium of 1 mmol.gDW^-1.h^-1 “as_is” : Their availability is the same as in the original inputted model.
undescribed_met_lb (negative float, optional) – Lower bound assigned to metabolites exchanges reactions that are not described in the given medium, when the “undescribed_metabolic_constraint” argument is set to “partially_constrained”. Default is -0.1

Returns:

model (cobra.Model)
constrained_medium_dict (dictionnary {met_id:(lower_bound,upper_bound)}) – Defines constraint of the ecosystem medium based on inputted medium data. Controls fluxes of metabolites entering the emodels external environment.

mimeco.utils.unrestrain_medium(model)

Opens the exchange reaction of individual models to enable exchange with paired model. Environment constraints will be reapplied at the scale of the ecosystem in the construction of the ecosystem model.

Parameters:: model (cobra.Model)
Returns:: model
Return type:: cobra.Model