IMAT Reference

API Documentation for the IMAT submodule

iMAT

Submodule with functions for adding iMAT constraints and objectives to a cobra model, and running iMAT

metworkpy.imat.imat_functions.add_imat_constraints(model, rxn_weights, epsilon: float = 0.001, threshold: float = 0.0001) → Model

Add the IMAT constraints to the model (returns new model, doesn’t update model in place).

Parameters:

model (cobra.Model) – A cobra.Model object to update with iMAT constraints.
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.

Returns:

The updated model.

Return type:

cobra.Model

metworkpy.imat.imat_functions.add_imat_constraints_(model: Model, rxn_weights: Series | dict, epsilon: float = 1, threshold: float = 0.01) → Model

Add the IMAT constraints to the model (updates the model in place).

Parameters:

model (cobra.Model) – A cobra.Model object to update with iMAT constraints.
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.

Returns:

The updated model.

Return type:

cobra.Model

metworkpy.imat.imat_functions.add_imat_objective(model: Model, rxn_weights: Series | dict) → Model

Add the IMAT objective to the model (doesn’t change passed model). Model must already have iMAT constraints added.

Parameters:

model (cobra.Model) – A cobra.Model object to update with iMAT constraints.
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.

Returns:

None

Return type:

unknown

metworkpy.imat.imat_functions.add_imat_objective_(model: Model, rxn_weights: Series | dict) → None

Add the IMAT objective to the model (updates the model in place). Model must already have iMAT constraints added.

Parameters:

model (cobra.Model) – A cobra.Model object to update with iMAT constraints.
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.

metworkpy.imat.imat_functions.compute_imat_objective(fluxes: Series, rxn_weights, epsilon: float = 1, threshold: float = 0.01)

Compute the iMAT objective value for a given set of fluxes.

Parameters:

fluxes (pandas.Series) – A pandas series of fluxes.
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.

Returns:

imat_objective – The iMAT objective value.

Return type:

float

metworkpy.imat.imat_functions.flux_to_binary(fluxes: Series, which_reactions: str = 'active', epsilon: float = 1, threshold: float = 0.01, tolerance=1e-07) → Series

Convert a pandas series of fluxes to a pandas series of binary values.

Parameters:

fluxes (pandas.Series) – A pandas series of fluxes.
which_reactions (str) – Which reactions should be the binary values? Options are “active”, “inactive”, “forward”, “reverse”, or their first letters. Default is “active”. “active” will return 1 for reactions with absolute value of flux greater than epsilon, and 0 for reactions with flux less than epsilon. “inactive” will return 1 for reactions with absolute value of flux less than threshold, and 0 for reactions with flux greater than threshold. “forward” will return 1 for reactions with flux greater than epsilon, and 0 for reactions with flux less than epsilon. “reverse” will return 1 for reactions with flux less than -epsilon, and 0 for reactions with flux greater than -epsilon.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
tolerance (float) – The tolerance of the solver. Default from cobra is 1e-7.

Returns:

A pandas series of binary values.

Return type:

pandas.Series

Notes

This doesn’t account for gene expression level, to determine highly expressed reactions which are considered on/off, the output of this function will need to be compared with reaction weights.

metworkpy.imat.imat_functions.imat(model: Model, rxn_weights: Series | dict, epsilon: float = 1, threshold: float = 0.01) → Solution

Function for performing iMAT analysis. Returns a cobra Solution object, with objective value and fluxes.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.

Returns:

A cobra Solution object with the objective value and fluxes.

Return type:

cobra.Solution

iMAT Iterator

Submodule provided an iterator over IMAT solutions by employing integer cut constraints

class metworkpy.imat.imat_iter.ImatBinaryVariables(rh_y_pos, rh_y_neg, rl_y_pos)

Bases: tuple

rh_y_neg: Alias for field number 1

rh_y_pos: Alias for field number 0

rl_y_pos: Alias for field number 2

class metworkpy.imat.imat_iter.ImatIter(model: Model, rxn_weights: Series | dict, output: Literal['model', 'binary-variables', 'reaction-activity'] = 'model', max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05, **kwargs)

Bases: object

Iterator for stepping through different possible iMAT solutions

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
output (Literal["model", "binary-variables", "reaction-activity"]) – What type of output is desired from the iterator, can be ‘model’, ‘binary-variables’, or ‘reaction-state’, see notes for details.
max_iter (int) – Maximum number of iMAT iterations to perform
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.

class metworkpy.imat.imat_iter.ImatIterBase(model: Model, rxn_weights: Series | dict, max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05)

Bases: ABC

Iterator for stepping through different possible iMAT solutions

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
max_iter (int) – Maximum number of iMAT iterations to perform
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.

class metworkpy.imat.imat_iter.ImatIterBinaryVariables(model: Model, rxn_weights: Series | dict, max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05)

Bases: ImatIterBase

Iterator for stepping through different possible iMAT solutions, returning a named tuple of pandas Series describing the state of all binary variables in the iMAT problem

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
max_iter (int) – Maximum number of iMAT iterations to perform
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.

Returns:

A named tuple with 3 fields

rh_y_pos: A pandas Series indexed by reaction id with the values indicating the state of the y+ variables associated with the high expression reactions. A value of 1 indicates that the reaction is active in the forward direction.
rh_y_neg: A pandas Series indexed by reaction id with the values indicating the state of the y- variables associated with the high expression reactions. A value of 1 indicates that the reaction is active in the reverse direction.
rl_y_pos: A pandas Series indexed by reaction id with the values indicating the state of the y+ variables associated with the low expression reactions. A value of 1 indicates that the reaction is inactive.

Return type:

unknown

class metworkpy.imat.imat_iter.ImatIterModels(model: Model, rxn_weights: Series | dict, method: Literal['simple', 'subset'] = 'simple', max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05)

Bases: ImatIterBase

Iterator for stepping through different possible iMAT solutions, returning an updated model for each iMAT solution, with modified reaction bounds to make it conform to the iMAT solution.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
method (Literal["simple", "subset]) – Which method to use to create the returned iMAT model, can be either ‘simple’, or ‘subset’, see notes for details.
max_iter (int) – Maximum number of iMAT iterations to perform
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.

Returns:

Every iteration returns a pandas Series of ReactionActivity describing the activity of reactions in the iMAT Model.

Return type:

Iterable[pd.Series[ReactionActivity]]

Notes

When creating an updated model based on the solution to the iMAT problem, two different methods can be selected, either

simple: This method enforces the activity constraints found during the iMAT solution, so reactions found to be active in the forward direction are forced to be active in the forward direction, and reactions found active in the reverse direction are forced to be active in the reverse direction, and reactions found to be inactive are forced to be inactive.
subset: This method instead finds which subset of reactions the iMAT problem indicates are not inactive, and allows only those reactions to carry flux (essentially inactive reactions are forced off).

The simple method can lead to the model being infeasible, and can also lead to reactions being considered essential because their knockout leads to forced active reactions no longer being able to carry flux. The subset method shouldn’t lead to as much infeasibility when performing essentiality analysis, but is a much lighter restriction on the model so may not fully incorporate the information provided by the gene expression weights.

class metworkpy.imat.imat_iter.ImatIterReactionActivities(model: Model, rxn_weights: Series | dict, max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05)

Bases: ImatIterBase

Iterator for stepping through different possible iMAT solutions, returning the reaction state of reactions with non-zero iMAT weights

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
max_iter (int) – Maximum number of iMAT iterations to perform
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.

Returns:

Every iteration returns a pandas Series of ReactionActivity describing the activity of reactions in the iMAT Model.

Return type:

Iterable[pd.Series[ReactionActivity]]

class metworkpy.imat.imat_iter.ReactionActivity(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum for representing reaction activity, with values of Inactive, ActiveReverse, ActiveForward, and Other

ActiveForward = 1

ActiveReverse = -1

Inactive = 0

Other = 404

metworkpy.imat.imat_iter.imat_iter_flux_sample(model: cobra.Model, rxn_weights: pd.Series[float], model_generation_method: Literal['simple', 'subset'] = 'simple', max_iter: int = 20, epsilon: float = 1, threshold: float = 0.01, objective_tolerance: float = 0.05, sampler: cobra.sampling.HRSampler | None = None, thinning: int = 100, num_samples: int = 1000, sampler_kwargs: dict[str, Any] | None = None, **kwargs) → pd.DataFrame[float]

Generate a flux sample from a Model by iterating over multiple optimal (or near-optimal depending on objective tolerance) iMAT solutions, and sampling from each

Parameters:

model (cobra.Model) – The base cobra Model to use for generating iMAT models which are then sampled from
rxn_weights (pd.Series[float]) – The qualitative weights indicating which reactions are high expression, or low expression, with values of 1 indicating high expression reactions, -1 indicating low expression reactions, and 0 indicating in between or unknown (see metworkpy.gpr.gpr_functions.gene_to_rxn_weights() for help generating this from qualitative gene weights, and metwor kpy.utils.expression_utils.expr_to_imat_gene_weights() for converting expression data into gene weights).
model_generation_method (Literal["simple", "subset"]) – Method to use when creating an updated model based on the results of the iMAT, can be either ‘simple’, or ‘subset’, see note for details.
max_iter (int) – Maximum number of iMAT updated models to iterate through
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-2). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for a solution to be considered optimal, the iterator will continue until no solution can be found which has a value of the iMAT objective function which is at least (1-objective_tolerance)*`optimal_imat_objective`. For example, a value of 0.05 (the default) indicates that the iterator will continue until no solution is found that is within 5% of the optimal objective.
sampler (cobra.sampling.HRSampler) – Sampler class from cobra to use for sampling (defaults to OptGPSampler), should be the class, not an instance of the class, so pass OptGPSampler, not OptGPSampler(). Keywords to the __init__function can be passed as a dict to sampler_kwargs.
thinning (int) – Thinning factor representing how often the sampler returns a sample, for example a value of 100 (the default) indicates that the sampler will return a sample every 100 steps. See Cobrapy documentation Will be overwritten by value in sampler_kwargs if thinning is provided there.
num_samples (int) – Number of samples to take per iMAT updated model so the total number of samples will be (number of iMAT updated models generated)*num_samples
sampler_kwargs (dict[str, Any]) – Keyword arguments passed to the __init__ function of the sampler class
**kwargs (dict[str, Any]) – Additional keyword arguments passed to the sampler’s sample function

Returns:

Flux samples from several iMAT updated models

Return type:

pd.DataFrame[float]

iMAT Model Creation

Submodule with functions for creating a context specific model using iMAT

metworkpy.imat.model_creation.fva_model(model, rxn_weights, epsilon, threshold, objective_tolerance, loopless: bool = True, warn_tolerance: bool = True, **kwargs)

Generate a context specific model by setting bounds on reactions based on FVA for an iMAT model.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for the objective value. The objective will be restricted to be within objective_tolerance*objective_value of the optimal objective value. (default: 5e-2)
loopless (bool) – Whether to use the loopless FVA method (default: True). If False, the standard FVA method will be used.
warn_tolerance – Issue a warning if there is a problem with finding the bounds of a particular reaction due to the lower bound being greater than the upper bound. This is normally caused by the solver tolerance, and the values will be swapped to get valid bounds for the reaction.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Notes

This method first creates a model with the iMAT constraints, and objective and then performs FVA to find the minimum and maximum flux for each reaction which allow for the objective to be within tolerance of optimal. These values are then set as the reaction bounds. This model is not guaranteed to have fluxes consistent with the optimal iMAT objective. This model will not include integer constraints, and so can be used for sampling.

metworkpy.imat.model_creation.generate_model(model: Model, rxn_weights: Series | dict, imat_solution: Solution | None = None, method: str = 'imat_restrictions', epsilon: float = 1.0, threshold: float = 0.1, objective_tolerance: float = 0.05, **kwargs)

Generate a context specific model using iMAT.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
imat_solution (cobra.Solution) – A pre-existing IMAT solution passed to the model creation methods, will only impact simple and subset as FVA and MILP solve altered versions of the IMAT problem.
method (str) – The method to use for generating the context specific model. Valid methods are: ‘imat_restrictions’, ‘simple_bounds’, ‘subset’, ‘fva’, ‘milp’.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for the objective value (used for imat_restrictions and fva methods). The objective will be restricted to be within objective_tolerance*objective_value of the optimal objective value. (default: 5e-2)

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

See also

imat_constraint_model: imat_restrictions method
simple_bounds_model: simple_bounds method
subset_model: subset method.
fva_model: fva based method
milp_model: milp method.

metworkpy.imat.model_creation.imat_constraint_model(model, rxn_weights, epsilon, threshold, objective_tolerance, **kwargs)

Generate a context specific model by adding iMAT constraints, and ensuring iMAT objective value is near optimal.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.
objective_tolerance (float) – The tolerance for the objective value. The objective will be restricted to be within objective_tolerance*objective_value of the optimal objective value. (default: 5e-2)

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Notes

This function first solves the iMAT problem, then adds a constraint to ensure that the iMAT objective value is within objective_tolerance*objective_value of the optimal objective value. This model will include integer constraints, and so won’t work with COBRApy sampling methods, but can be used with metworkpy.sampling.corner_sampling. If you want to use the model with the COBRApy sampling methods, use any of the other methods.

metworkpy.imat.model_creation.milp_model(model, rxn_weights, epsilon, threshold, **kwargs)

Generate a context specific model by setting bounds on reactions based on a set of mixed integer linear programming problems.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Notes

This method first creates a model with the iMAT constraints, and objective and then solves a set of mixed integer linear programming problems, where each reaction is set to be inactive, active in the forward direction, and active in the reverse direction. The reaction bounds are then set based on the results of the MILP problems. This model is not guaranteed to have fluxes consistent with the optimal iMAT objective. This model will not include integer constraints, and so can be used for sampling.

metworkpy.imat.model_creation.simple_bounds_model(model, rxn_weights: dict | Series, epsilon: float, threshold: float, imat_solution: Solution | None = None, **kwargs)

Generate a context specific model by setting bounds on reactions based on iMAT solution.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.
imat_solution (cobra.Solution) – A preexisting IMAT solution, if not provided will be computed when function is called

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Notes

This method first solves the iMAT solution, then for reactions found to be lowly expressed (weight<0), and inactive (flux<threshold), the reaction bounds are set to (-threshold, threshold), (0, threshold), or (-threshold, 0) depending on reversibility. For reactions found to be highly expressed and active in the forward direction (weight>0, flux>epsilon), the reaction bounds are set to (epsilon, ub), or (lb, ub) if lb>epsilon. For reactions found to be highly expressed and active in the reverse direction (weight>0, flux<-epsilon), the reaction bounds are set to (lb, -epsilon), or (lb, ub) if ub<-epsilon. This model will not include integer constraints, and so can be used for sampling.

metworkpy.imat.model_creation.subset_model(model: Model, rxn_weights: dict | Series, epsilon: float, threshold: float, imat_solution: Solution | None = None, **kwargs)

Generate a context specific model by knocking out reactions found to be inactive by iMAT.

Parameters:

model (cobra.Model) – A cobra.Model object to use for iMAT
rxn_weights (dict | pandas.Series) – A dictionary or pandas series of reaction weights.
epsilon (float) – The epsilon value to use for iMAT (default: 1). Represents the minimum flux for a reaction to be considered on.
threshold (float) – The threshold value to use for iMAT (default: 1e-1). Represents the maximum flux for a reaction to be considered off.
imat_solution (cobra.Solution) – A preexisting IMAT solution, if not provided will be computed when function is called

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Notes

This method first solves the iMAT solution, then for reactions found to be lowly expressed (weight<0), and inactive (flux<threshold), the reaction bounds are set to (-threshold, threshold). This model will not include integer constraints, and so can be used for sampling.