imatpy package

Submodules

imatpy.imat module

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

imatpy.imat.add_imat_constraints(model, rxn_weights, epsilon: float = 0.001, threshold: float = 0.0001) → Model[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

The updated model.

Return type:

cobra.Model

imatpy.imat.add_imat_constraints_(model: Model, rxn_weights: Series | dict, epsilon: float = 0.01, threshold: float = 0.001) → Model[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

The updated model.

Return type:

cobra.Model

imatpy.imat.add_imat_objective(model: Model, rxn_weights: Series | dict) → Model[source]

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

imatpy.imat.add_imat_objective_(model: Model, rxn_weights: Series | dict) → None[source]

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.

Returns:

None

imatpy.imat.compute_imat_objective(fluxes: Series, rxn_weights, epsilon: float = 0.01, threshold: float = 0.001)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

The iMAT objective value.

imatpy.imat.flux_to_binary(fluxes: Series, which_reactions: str = 'active', epsilon: float = 0.01, threshold: float = 0.001, tolerance=1e-07) → Series[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). 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

imatpy.imat.imat(model: Model, rxn_weights: Series | dict, epsilon: float = 0.01, threshold: float = 0.001) → Solution[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). 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

imatpy.model_creation module

Submodule with functions for creating a context specific model using iMAT

imatpy.model_creation.fva_model(model, rxn_weights, epsilon, threshold, objective_tolerance, loopless: bool = True)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). 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.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Note

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.

imatpy.model_creation.generate_model(model: Model, rxn_weights: Series | dict, method: str = 'imat_restrictions', epsilon: float = 0.01, threshold: float = 0.001, objective_tolerance: float = 0.05)[source]

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.

  • method (str) – The method to use for generating the context specific model. Valid methods are: ‘imat_restrictions’, ‘simple_bounds’, ‘eliminate_below_threshold’, ‘fva’, ‘milp’.

  • epsilon (float) – The epsilon value to use for iMAT (default: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). 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() for more information on the imat_restrictions method.
simple_bounds_model() for more information on the simple_bounds method.
subset_model() for more information on the eliminate_below_threshold method.
fva_model() for more information on the fva method.
milp_model() for more information on the milp method.
imatpy.model_creation.imat_constraint_model(model, rxn_weights, epsilon, threshold, objective_tolerance)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). 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

Note

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 can not be used for sampling. If you want to use the model for sampling, use any of the other methods.

imatpy.model_creation.milp_model(model, rxn_weights, epsilon, threshold)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Note

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 include integer constraints, and so can not be used for sampling.

imatpy.model_creation.simple_bounds_model(model, rxn_weights, epsilon, threshold)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Note

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.

imatpy.model_creation.subset_model(model, rxn_weights, epsilon, threshold)[source]

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: 1e-3). Represents the minimum flux for a reaction to be considered on.

  • threshold (float) – The threshold value to use for iMAT (default: 1e-4). Represents the maximum flux for a reaction to be considered off.

Returns:

A context specific cobra.Model.

Return type:

cobra.Model

Note

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.

imatpy.model_utils module

Module for model utilities

imatpy.model_utils.model_eq(model1: Model, model2: Model, verbose: bool = False) → bool[source]

Check if two cobra models are equal.

Parameters:

  • model1 (cobra.Model) – The first model to compare.

  • model2 (cobra.Model) – The second model to compare.

  • verbose (bool) – Whether to print where the models differ (default: False).

Returns:

True if the models are equal, False otherwise.

Return type:

bool

imatpy.model_utils.read_model(model_path, file_type=None)[source]

Read a model from a file

Parameters:

  • model_path (str | pathlib.Path) – Path to the model file

  • file_type (str) – Type of the file

Returns:

The model

imatpy.model_utils.write_model(model, model_path, file_type=None)[source]

Write a model to a file

Parameters:

  • model (cobra.Model) – Model to write

  • model_path (str) – Path to the model file

  • file_type (str) – Type of the file

Returns:

Nothing

imatpy.parse_gpr module

imatpy.parse_gpr.eval_gpr(gpr: str, gene_weights: Series, fn_dict: dict = None) → Any | None[source]

Evaluate a single GPR string using the provided gene weights and function dictionary.

Parameters:

  • gpr (str) – str: A single GPR string

  • gene_weights (pd.Series) – pd.Series: A series of gene weights

  • fn_dict (dict) – dict: A dictionary of functions to use for each operator

Returns:

The GPR score

Return type:

float | None

imatpy.parse_gpr.gene_to_rxn_weights(model: Model, gene_weights: Series, fn_dict: dict = None, fill_val: Any = 0) → Series[source]

Convert a gene weights series to a reaction weights series using the provided function dictionary.

Parameters:

  • model (cobra.Model) – cobra.Model: A cobra model

  • gene_weights (pd.Series) – pd.Series: A series of gene weights

  • fn_dict (dict) – dict: A dictionary of functions to use for each operator

  • fill_val (Any) – Any: The value to fill missing values with

Returns:

A series of reaction weights

Return type:

pd.Series

imatpy.parse_gpr.process_token(token, postfix, operator_stack, precedence)[source]

The process_token function takes in a token, the postfix list, the operator stack and precedence dictionary. It performs the shunting yard algorithm for a the single provided token.

Parameters:

  • token (str) – Current token

  • postfix (list[str]) – Current state of output

  • operator_stack (list[str]) – Current operator stack

  • precedence (dict[str:int]) – Determines the operators precedence

Returns:

Nothing

Return type:

None

imatpy.parse_gpr.str_to_list(in_string: str, replacements: dict = None) → list[str][source]

Convert a string to a list of strings, splitting on whitespace and parentheses.

Parameters:

  • in_string (str) – str: Specify the input string

  • replacements (dict) – dict: Replace certain strings with other strings before splitting, uses regex

Returns:

A list of strings

Return type:

list[str]

imatpy.parse_gpr.to_postfix(infix: list[str], precedence: dict = None) → list[str][source]

Convert an infix expression to postfix notation. :param infix: list[str]: A list of strings representing an infix expression :type infix: list[str] :param precedence: Dictionary of operators determining precedence :type precedence: dict[str:int] :return: A list of strings representing the postfix expression :rtype: list[str]

Module contents