micom.community
¶
A class representing a microbial or tissue community.
Module Contents¶
Attributes¶
- micom.community._ranks = ['kingdom', 'phylum', 'class', 'order', 'family', 'genus', 'species', 'strain'][source]¶
- class micom.community.Community(taxonomy, model_db=None, id=None, name=None, rel_threshold=1e-06, solver=None, progress=True, max_exchange=100, mass=1)[source]¶
Bases:
cobra.Model
A community of models.
This class represents a community of individual models. It was designed for microbial communities but may also be used for multi-tissue or tissue-cell mixture models as long as all individuals exist within a single enclosing compartment.
- __add_exchanges(self, reactions, info, external_compartment='e', internal_exchange=1000)[source]¶
Add exchange reactions for a new model.
- optimize_single(self, id)[source]¶
Optimize growth rate for one individual.
optimize_single will calculate the maximal growth rate for one individual member of the community.
Notes
This might well mean that growth rates for all other individuals are low since the individual may use up all available resources.
- Parameters
id (str) – The ID of the individual to be optimized.
fluxes (boolean, optional) – Whether to return all fluxes. Defaults to just returning the maximal growth rate.
- Returns
The maximal growth rate for the given taxa.
- Return type
float
- optimize_all(self, progress=False)[source]¶
Return solutions for individually optimizing each model.
Notes
This might well mean that growth rates for all other individuals are low since the individual may use up all available resources. As a consequence the reported growth rates may usually never be obtained all at once.
- Parameters
progress (boolean, optional) – Whether to show a progress bar.
- Returns
The maximal growth rate for each taxa.
- Return type
pandas.Series
- optimize(self, fluxes=False, pfba=False, raise_error=False, atol=None, rtol=None)[source]¶
Optimize the model using flux balance analysis.
This is the primary accessor for optimization in MICOM and should be used for all optimizations. Different from cobrapy this will not return the full solution by default but only growth rates which is much quicker. You can request a full solution by setting the fluxes and pFBA arguments.
Note
for OSQP this will use an additional quadratic regularization in order to convert all LP problems to QPs and stabilize the solution. This may not perform well if the community growth rate is larger 1000 (which it should never be as this would be a doubling time of a few seconds).
- Parameters
slim (boolean, optional) – Whether to return a slim solution which does not contain fluxes, just growth rates.
raise_error (boolean, optional) – Should an error be raised if the solution is not optimal. Defaults to False which will either return a solution with a non-optimal status or None if optimization fails.
fluxes (boolean, optional) – Whether to return the fluxes as well.
pfba (boolean, optional) – Whether to obtain fluxes by parsimonious FBA rather than “classical” FBA. This is highly recommended.
atol (float) – Absolute tolerance for the growth rates. If None will use the solver tolerance.
rtol (float) – Relative tolerqance for the growth rates. If None will use the solver tolerance.
- Returns
The solution after optimization or None if there is no optimum.
- Return type
micom.CommunitySolution
- property abundances(self)[source]¶
pandas.Series: The normalized abundances.
Setting this attribute will also trigger the appropriate updates in the exchange fluxes and the community objective.
- set_abundance(self, value, normalize=True)[source]¶
Change abundances for one or more taxa.
- Parameters
value (array-like object) – The new abundances. Must contain one value for each taxon. Can be a named object like a pandas Series.
normalize (boolean, optional) – Whether to normalize the abundances to a total of 1.0. Many things in micom asssume that this is always the case. Only change this if you know what you are doing :O
- property taxonomy(self)[source]¶
pandas.DataFrame: The taxonomy used within the model.
This attribute only returns a copy.
- property modification(self)[source]¶
str: Denotes modifications to the model currently applied.
Will be None if the community is unmodified.
- property exchanges(self)[source]¶
list: Return all exchange reactions in the model.
Uses several heuristics based on the reaction name and compartments to exclude reactions that are not exchange reactions.
- property internal_exchanges(self)[source]¶
list: Return all internal exchanges.
Internal exchanges are exchanges between individual taxa and the medium.
- property build_metrics(self)[source]¶
pd.Series: Returns general metrics for database matching.
Only available when built using a model database.
- optcom(self, strategy='lagrangian', min_growth=0.0, fluxes=False, pfba=True)[source]¶
Run OptCom for the community.
OptCom methods are a group of optimization procedures to find community solutions that provide a tradeoff between the cooperative community growth and the egoistic growth of each individual 1. micom provides several strategies that can be used to find optimal solutions:
“moma”: Minimization of metabolic adjustment. Simultaneously optimizes the community objective (maximize) and the cooperativity cost (minimize). This method finds an exact maximum but doubles the number of required variables, thus being slow.
“lmoma”: The same as “moma” only with a linear representation of the cooperativity cost (absolute value).
“original”: Solves the multi-objective problem described in 1. Here, the community growth rate is maximized simultanously with all individual growth rates. Note that there are usually many Pareto-optimal solutions to this problem and the method will only give one solution. This is also the slowest method.
- Parameters
community (micom.Community) – The community to optimize.
strategy (str) – The strategy used to solve the OptCom formulation. Defaults to “lagrangian” which gives a decent tradeoff between speed and correctness.
min_growth (float or array-like) – The minimal growth rate required for each individual. May be a single value or an array-like object with the same length as there are individuals.
fluxes (boolean) – Whether to return the fluxes as well.
pfba (boolean) – Whether to obtain fluxes by parsimonious FBA rather than “classical” FBA.
- Returns
The solution of the optimization. If fluxes==False will only contain the objective value, community growth rate and individual growth rates.
- Return type
micom.CommunitySolution
References
- cooperative_tradeoff(self, min_growth=0.0, fraction=1.0, fluxes=False, pfba=False, atol=None, rtol=None)[source]¶
Find the best tradeoff between community and individual growth.
Finds the set of growth rates which maintian a particular community growth and spread up growth across all taxa as much as possible. This is done by minimizing the L2 norm of the growth rates with a minimal community growth.
- Parameters
min_growth (float or array-like, optional) – The minimal growth rate required for each individual. May be a single value or an array-like object with the same length as there are individuals.
fraction (float or list of floats in [0, 1]) – The minum percentage of the community growth rate that has to be maintained. For instance 0.9 means maintain 90% of the maximal community growth rate. Defaults to 100%.
fluxes (boolean, optional) – Whether to return the fluxes as well.
pfba (boolean, optional) – Whether to obtain fluxes by parsimonious FBA rather than “classical” FBA. This is highly recommended.
atol (float) – Absolute tolerance for the growth rates. If None will use the solver tolerance.
rtol (float) – Relative tolerqance for the growth rates. If None will use the solver tolerance.
- Returns
The solution of the optimization. If fluxes==False will only contain the objective value, community growth rate and individual growth rates. If more than one fraction value is given will return a pandas Series of solutions with the fractions as indices.
- Return type
micom.CommunitySolution or pd.Series of solutions
- knockout_taxa(self, taxa=None, fraction=1.0, method='change', progress=True, diag=True)[source]¶
Sequentially knowckout a list of taxa in the model.
This uses cooperative tradeoff as optimization criterion in order to get unqiue solutions for individual growth rates. Requires a QP solver to work.
- Parameters
taxa (str or list of strs) – Names of taxa to be knocked out.
fraction (float in [0, 1], optional) – Percentage of the maximum community growth rate that has to be maintained. Defaults to 100%.
method (str, optional) – One of “raw”, “change” or “relative change” that dictates whether to return the new growth rate (raw), the change in growth rate new - old or the relative change ([new - old] / old).
progress (bool, optional) – Whether to show a progress bar. On by default.
diag (bool, optional) – Whether the diagonal should contain values as well. If False will be filled with NaNs.
- Returns
A data frame with one row for each knockout and growth rates in the columns. Here the row name indicates which taxon has been knocked out and the columns contain the growth changes for all taxa in that knockout.
- Return type
pandas.DataFrame