pymgpipe package

Submodules

pymgpipe.coupling module

pymgpipe.coupling.add_coupling_constraints(model, u_const=0.01, C_const=400)

Adding coupling constraints to community-level models

Parameters:

• model (optlang.interface.Model) – LP problem

• u_const (float) – U flexibility constant

• C_const (float) – C flexibility constant

Notes

Coupling constraints are essentially a set of lower/upper bound constraints that scale reaction fluxes to the relative abundance of the microbe they belong to, like so- Imagine a reaction -1000 <= My_reaction_taxa_A <= 1000. Adding coupling constraints would redefine the bounds like so-

-C_const - (u_counts * <abundance of taxa A>) <= My_reaction_taxa_A <= C_const + (u_counts * <abundance of taxa A>)

pymgpipe.coupling.remove_coupling_constraints(model)

Removing coupling constraints to community-level models

Parameters:

model (optlang.interface.Model) – LP problem

Notes

Removes all coupling constraints from model (if they exist)

pymgpipe.diet module

pymgpipe.diet.add_diet_to_model(model, diet, force_uptake=True, essential_metabolites=None, micronutrients=None, vaginal=False, threshold=0.8, check=True)

Add pymgpipe-adapated diet to model as defined by original mgPipe paper (see README for more details)

Parameters:

• model (optlang.interface.model) – LP problem

• diet (pandas.DataFrame | str) – Path to diet or dataframe

• essential_metabolites (list) – Custom of essential metabolites (uses pre-defined list by default)

• micronutrients (list) – Custom list of micronutrients (uses pre-defined list by default)

• vaginal (bool) – Whether or not this is a vaginal diet

• threshold (float) – Value between 0 and 1 that defines how strict the diet constraints are (with 1 being the least strict)

• check (bool) – Check whether or not this diet is feasible (can take some time depending on size of model)

pymgpipe.diet.get_available_diets()

Returns all diets that come pre-packaged with pymgpipe

pymgpipe.diet.get_diet(model)

Returns existing diet from model

pymgpipe.diet.remove_diet(model)

Removes existing diet from model

pymgpipe.fva module

class pymgpipe.fva.FVA_TYPE(value)

Bases: Enum

An enumeration.

FAST = 2

REGULAR = 1

class pymgpipe.fva.VFFVA

Bases: object

property path

pymgpipe.fva.fva(model=None, fva_type=FVA_TYPE.REGULAR, reactions=None, regex=None, ex_only=True, solver='gurobi', threads=1, write_to_file=False, out_file=None, parallel=True, threshold=1e-05, scaling=0, mem_aff='none', schedule='dynamic', objective_percent=None, force=False)

Run Flux Variability Analysis (FVA) on target reactions

Available FVA types are regular and fast. Fast FVA is significantly faster, but requires both a CPLEX license and full install of the VFFVA package. Additionally, all problems need to be in .mps format if using fast FVA type. For more information, see VFFVA package- https://github.com/marouenbg/VFFVA.

Parameters:

• model (str | optlang.Model) – model you want to run FVA on

• fva_type (str) – FVA type used to compute min/max values, allowed values are fast and regular

• reactions (list) – List of reactions you want to target

• regex (str) – Regex match for list of reactions you want to target

• ex_only (bool) – Run FVA on exchange reactions only

• solver (str) – LP solver used, allowed values are gurobi and cplex

• threads (float) – How many threads to use to run FVA

• write_to_file (bool) – Setting this to True will save results to out_file

• out_file (str) – Name of file you want to save results (should have .csv extension)

• parallel (bool) – If set to True, will use number of threads specified by threads parameter

• scaling (float) – VFFVA specific parameter, see VFFVA package- https://github.com/marouenbg/VFFVA.

• mem_aff (str) – VFFVA specific parameter, see VFFVA package- https://github.com/marouenbg/VFFVA.

• schedule (str) – VFFVA specific parameter, see VFFVA package- https://github.com/marouenbg/VFFVA.

• objective_percent (float) – Takes value between 0-100. If not set to None, will compute objective and constrain to specified percentage of maximum value before running FVA

• force (bool) – Will compute FVA and overwrite existing file (if file is found with target reactions)

Notes

If computation is cut short prematurely, this function will pick up where it left off based on which reactions are already present in out_file.

pymgpipe.io module

exception pymgpipe.io.UnsupportedSolverException(msg='Unrecognized solver. Supported solvers include gurobi and cplex', *args, **kwargs)

Bases: Exception

pymgpipe.io.load_cobra_model(file, solver='gurobi')

Loads and returns COBRA model

pymgpipe.io.load_model(path, solver='gurobi')

Loads optlang.interface.Model from either an LP file (.lp or .mps) or any of the available COBRA file types (.xml, .mat, etc)

Returns: optlang.interface.Model

pymgpipe.io.show_available_solvers()

pymgpipe.io.suppress_stdout()

pymgpipe.io.write_cobra_model(model, file)

Writes COBRA model to file

Warning: COBRA won’t save any custom modifications added to the model (i.e. coupling constraints, diet, etc). For this reason, we recommend working and using the corresponding optlang LP problems.

pymgpipe.io.write_lp_problem(model, out_file=None, compress=True, force=True)

Writes optlang.interface.Model out to file (will compress by default)

pymgpipe.main module

pymgpipe.main.build_models(coverage_file, taxa_dir, solver='gurobi', threads=1, samples=None, parallel=True, lp_type='.mps', cobra_type='.xml', out_dir='./', coupling_constraints=True, diet_fecal_compartments=False, remove_reverse_vars_from_lp=False, hard_remove=False, abundance_threshold=1e-06, diet=None, vaginal=False, essential_metabolites=None, micronutrients=None, force_uptake=True, diet_threshold=0.8, compress=True, compute_metrics=True, force=False, sample_prefix='mc')

Build community COBRA models using mgpipe-like compartments and constraints.

This function is pymgpipe’s main model building function, and can be used to build models for either one or multiple samples.

Parameters:

• coverage_file (pandas.DataFrame | str) – Abundance matrix with taxa as rows and samples as columns

• taxa_dir (str) – Directory containing individual strain/species taxa models (file names corresponding to index of coverage matrix)

• out_dir (str) – Directory to save output of this function (models, LP problems, etc.), defaults to cwd

• diet_fecal_compartments (bool) – Build models with mgpipe’s diet/fecal compartmentalization, defaults to False

• coupling_constraints (bool) – Add mgpipe’s abundance coupling constraints to internal reactions, defaults to True

• remove_reverse_vars_from_lp (bool) – Remove reverse variables that are added into COBRApy models

• hard_remove (bool) – If set to True, variables will be removed entirely from models, which can be a time consuming process. Having it set to False will remove them by setting their bounds to 0.

• diet (str) – Name of diet or file you want to impose on models (can be one diet or personalized)

• vaginal (bool) – Impose vaginal diet constraints to support vaginal diet

• essential_metabolites (list) – List of metabolites to include as essential within the diet

• micronutrients (list) – List of metabolites to include as micronutrients within diet

• force_uptake (bool) – Force minimum uptake of nutrients from diet

• diet_threshold (float) – Threshold on imposed diet uptake, i.e. lb < metabolite < (threshold * lb)

• solver (str) – LP solver (gurobi or cplex) used to solve models, defaults to gurobi

• parallel (bool) – Samples will be built in parallel if set to True

• threads (int) – Number of threads to use if building in parallel

• lp_type (str) – File type for LP problem (either .mps or .lp), defaults to .mps

• cobra_type (str) – File type for COBRA model (.xml, .mat, .json), defaults to .xml

• compress (bool) – Models and LP problems will be saved as compressed files if set to True, defaults to True

• compute_metrics (bool) – Compute diversity metrics for built models, defaults to True

Notes

COBRA models written to out_dir/models/

LP problems written to out_dir/problems/

All modifications done at the level of the LP (i.e. coupling constraints, diet) are not saved when writing COBRA models to file. For this reason, it is always recommended to work with LP models in the problems/ folder.

pymgpipe.modeling module

pymgpipe.modeling.build(abundances, sample, taxa_directory, threshold=1e-06, diet_fecal_compartments=True, solver='gurobi')

Build community COBRA model using mgpipe-like compartments and constraints.

This function is pymgpipe’s main model building function, can can be used to build a single model (with no further modifications)

Parameters:

• abundances (pandas.DataFrame | str) – Abundance matrix with taxa as rows and samples as columns

• sample (str) – Label corresponding to the sample you want to build (needs to match up to column name in abundance matrix)

• taxa_directory (str) – Directory containing individual strain/species taxa models (file names corresponding to index of coverage matrix)

• threshold (float) – Abundance threshold, any taxa with an abundance less than this value will be left out and abundances will be re-normalized

• diet_fecal_compartments (bool) – Build models with mgpipe’s diet/fecal compartmentalization, defaults to False

• solver (str) – LP solver (gurobi or cplex) used to solve models, defaults to gurobi

pymgpipe.nmpc module

pymgpipe.nmpc.compute_nmpcs(samples, out_dir='./', out_file='nmpcs.csv', objective_out_file='community_objectives.csv', fluxes_out_file='all_fluxes.csv', reactions=None, regex=None, ex_only=True, solver='gurobi', threads=1, parallel=True, diet_fecal_compartments=True, force=False, threshold=1e-05, write_to_file=True, fva_type=FVA_TYPE.REGULAR, objective_percent=100, scaling=0, mem_aff='none', schedule='dynamic', signed=False)

Compute NMPCs as well as associated reaction metrics on specified list (or directory) of samples

This function is computes NMPCs at the level of the optlang LP problem to leverage speed of low-level representation. Available FVA types are regular and fast. Fast FVA is significantly faster, but requires both a CPLEX license and full install of the VFFVA package. Additionally, all problems need to be in .mps format if using fast FVA type. For more information, see VFFVA package- https://github.com/marouenbg/VFFVA.

NMPCs are calculated as the max fluxes secreted by the fecal compartment (positive values only) summed with the min flux uptaken by the diet compartment (negative values only). In cases where models are not build with diet/fecal compartments, NMPCs are simply calculated as the sum of the max and min fluxes.

Parameters:

• samples (list | str) – List of samples or directory containing samples

• out_dir (str) – Directory to output results

• out_file (str) – Name of file containing final NMPCs

• objective_out_file (str) – Name of file containing community objectives

• fluxes_out_file (str) – Name of file containing fluxes

• reactions (list) – List of reactions to run NMPCs on

• regex (str) – Regex match for list of reactions to run NMPCs on

• diet_fecal_compartments (bool) – Whether or not models are built with diet/fecal compartmentalization

• ex_only (bool) – Compute NMPCs on exchange reactions only

• fva_type (str) – FVA type used to compute NMPCs, allowed values are fast and regular

• solver (str) – LP solver used to compute NMPCs, allowed values are gurobi and cplex

• obj_optimality (float) – Percent of optimal objective value constrained during NMPC computation

• threshold (float) – Fluxes below threshold will be set to 0

• write_to_file (bool) – Write results to file

Notes

If computation is cut short prematurely, this function will pick up where it left off based on which samples are already present in out_file.

pymgpipe.utils module

class pymgpipe.utils.Constants

Bases: object

DIET_REGEX = '^(Diet_)?(?i)EX_((?!biomass|community).)*\\[d\\]$'

EX_REGEX = '^(Diet_)?(?i)EX_((?!biomass|community).)*(_m|\\[u\\]|\\[d\\]|\\[fe\\])$'

FE_REGEX = '^EX_((?!biomass|community).)*\\[fe\\]$'

exception pymgpipe.utils.InfeasibleModelException

Bases: Exception

pymgpipe.utils.constrain_reactions(model, flux_map, threshold=0.0)

Constrains reactions within model to specific value (or range of values)

Parameters:

• model (optlang.interface.model) – LP problem

• flux_map (dictionary) – Dictionary defining flux value for each reaction you want to constrain

• threshold (float) – Fixed value defining flexibility threshold (not a percentage!)

Example: Passing in the following dictionary {‘EX_reactionA’: 400} with a threshold of 50 will set the bounds for this reaction to 350 <= EX_reactionA <= 450

pymgpipe.utils.get_abundances(model)

Returns taxa abundances within community-level model

pymgpipe.utils.get_net_reactions(model, reactions=None, regex=None)

Fetches NET reactions from model

Parameters:

• model (optlang.interface.model) – LP problem

• regex (str) – Regex string corresponding to list of reactions you want to return

• reactions (list) – List of reactions you want to return

Notes: By default, COBRA adds a reverse variable for every forward variable within the model. Therefore, to calculate the flux going through reaction_A for example, you must subtract the forward and reverse fluxes like so- reaction_A - reaction_A_reverse

pymgpipe.utils.get_reaction_bounds(model, id)

Fetches reaction lower and upper bounds

pymgpipe.utils.get_reactions(model, reactions=None, regex=None, include_reverse=False)

Fetches reactions from model

Parameters:

• model (optlang.interface.model) – LP problem

• regex (str) – Regex string corresponding to list of reactions you want to return

• reactions (list) – List of reactions you want to return

• include_reverse (bool) – Whether or not you want to return reverse variables as well (if model contains reverse variables)

Returns: List of optlang.interface.Variable

pymgpipe.utils.get_reverse_var(model, v)

Returns associated reverse variable

pymgpipe.utils.load_dataframe(m, return_empty=False)

pymgpipe.utils.port_mgpipe_model(path, remove_reverse=True, hard_remove=True)

Converts pymgpipe model to mgPipe model for backwards-compatibility

pymgpipe.utils.remove_reverse_vars(model, hard_remove=False)

Removes all reverse variables from model

Parameters:

• model (optlang.interface.model) – LP problem

• hard_remove (bool) – Setting hard_remove to True will physically remove the variables from the model, whereas setting it to False will only set the lower/upper bounds to 0

Notes: By default, COBRA adds a reverse variable for every forward variable within the model. Therefore, to calculate the flux going through reaction_A for example, you must subtract the forward and reverse fluxes like so- reaction_A - reaction_A_reverse. This function removes all reverse variables to make calculations a lot simpler and faster. Also, reduces the size of the models by roughly 50%!

pymgpipe.utils.set_objective(model, obj_expression, direction='min')

Sets model optimization objective (optlang.interface.Objective)

Notes: obj_expression can either be an optlang.interface.Objective, a string defining a specific variable, or a list of variables (in which case it will set objective to the sum of said reactions)

pymgpipe.utils.set_reaction_bounds(model, id, lb, ub)

Sets reaction lower and upper bounds

pymgpipe.utils.solve_model(model, regex=None, reactions=None, solver='gurobi', verbosity=0, presolve=True, method='primal', flux_threshold=None, ex_only=True)

Solves optlang.interface.Model

Parameters:

• model (optlang.interface.model) – LP problem

• regex (str) – Regex string corresponding to list of reactions you want to return

• reactions (list) – List of reactions you want to return

• ex_only (bool) – Only return fluxes for exchange reactions (will be overridden by either regex or reactions param)

• flux_threshold (float) – Any flux below this threshold value will be set to 0

Notes: presolve and method are both solver-specific parameters. Please refer to https://optlang.readthedocs.io/en/latest/ for more info.

Module contents