cobra.util ========== .. py:module:: cobra.util Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/cobra/util/array/index /autoapi/cobra/util/context/index /autoapi/cobra/util/process_pool/index /autoapi/cobra/util/solver/index /autoapi/cobra/util/util/index Attributes ---------- .. autoapisummary:: cobra.util.OPTLANG_TO_EXCEPTIONS_DICT cobra.util.CONS_VARS cobra.util.logger cobra.util.solvers cobra.util.qp_solvers cobra.util.has_primals Exceptions ---------- .. autoapisummary:: cobra.util.OptimizationError cobra.util.SolverNotFound Classes ------- .. autoapisummary:: cobra.util.HistoryManager cobra.util.ProcessPool cobra.util.Components cobra.util.AutoVivification Functions --------- .. autoapisummary:: cobra.util.create_stoichiometric_matrix cobra.util.nullspace cobra.util.constraint_matrices cobra.util.get_context cobra.util.resettable cobra.util.get_context cobra.util.linear_reaction_coefficients cobra.util._valid_atoms cobra.util.set_objective cobra.util.interface_to_str cobra.util.get_solver_name cobra.util.choose_solver cobra.util.check_solver cobra.util.add_cons_vars_to_problem cobra.util.remove_cons_vars_from_problem cobra.util.add_absolute_expression cobra.util.fix_objective_as_constraint cobra.util.check_solver_status cobra.util.assert_optimal cobra.util.add_lp_feasibility cobra.util.add_lexicographic_constraints cobra.util.format_long_string cobra.util.show_versions Package Contents ---------------- .. py:function:: create_stoichiometric_matrix(model: cobra.Model, array_type: str = 'dense', dtype: Optional[numpy.dtype] = None) -> Union[numpy.ndarray, scipy.sparse.dok_matrix, scipy.sparse.lil_matrix, pandas.DataFrame] Return a stoichiometric array representation of the given model. The the columns represent the reactions and rows represent metabolites. S[i,j] therefore contains the quantity of metabolite `i` produced (negative for consumed) by reaction `j`. :param model: The cobra model to construct the matrix for. :type model: cobra.Model :param array_type: The type of array to construct. "dense" will return a standard numpy.ndarray. "dok", or "lil" will construct a sparse array using scipy of the corresponding type. "DataFrame" will give a pandas.DataFrame with metabolite as indices and reaction as columns. :type array_type: {"dense", "dok", "lil", "DataFrame"} :param dtype: The desired numpy data type for the array (default numpy.float64). :type dtype: numpy.dtype, optional :returns: The stoichiometric matrix for the given model. :rtype: matrix of class `dtype` :raises ValueError: If sparse matrix is used and scipy is not installed. :raises .. deprecated:: 0.18.1: "DataFrame" option for `array_type` will be replaced with "frame" in future versions. .. py:function:: nullspace(A: numpy.ndarray, atol: float = 1e-13, rtol: float = 0.0) -> numpy.ndarray Compute an approximate basis for the nullspace of A. The algorithm used by this function is based on the Singular Value Decomposition (SVD) of `A`. :param A: `A` should be at most 2-D. 1-D array with length k will be treated as a 2-D with shape (1, k). :type A: numpy.ndarray :param atol: The absolute tolerance for a zero singular value. Singular values smaller than `atol` are considered to be zero (default 1e-13). :type atol: float, optional :param rtol: The relative tolerance. Singular values less than `rtol * smax` are considered to be zero, where `smax` is the largest singular value (default 0.0). :type rtol: float, optional :returns: If `A` is an array with shape (m, k), then `ns` will be an array with shape (k, n), where `n` is the estimated dimension of the nullspace of `A`. The columns of `ns` are a basis for the nullspace; each element in numpy.dot(A, ns) will be approximately zero. :rtype: numpy.ndarray .. rubric:: Notes This is taken from the numpy cookbook. If both `atol` and `rtol` are positive, the combined tolerance is the maximum of the two; that is: .. math:: \mathtt{tol} = \max(\mathtt{atol}, \mathtt{rtol} * \mathtt{smax}) Singular values smaller than `tol` are considered to be zero. .. py:function:: constraint_matrices(model: cobra.Model, array_type: str = 'dense', zero_tol: float = 1e-06) -> NamedTuple Create a matrix representation of the problem. This is used for alternative solution approaches that do not use "optlang". The function will construct the equality matrix, inequality matrix and bounds for the complete problem. :param model: The model from which to obtain the LP problem. :type model: cobra.Model :param array_type: The type of array to construct. "dense" will return a standard numpy.ndarray. "dok", or "lil" will construct a sparse array using scipy of the corresponding type. "DataFrame" will give a pandas.DataFrame with metabolite as indices and reaction as columns. :type array_type: {"dense", "dok", "lil", "DataFrame"} :param zero_tol: The zero tolerance used to judge whether two bounds are the same (default 1e-6). :type zero_tol: float, optional :returns: A named tuple consisting of 6 matrices and 2 vectors: - "equalities" is a matrix `S` such that `S * vars = b`. It includes a row for each constraint and one column for each variable. - "b" is the right side of the equality equation such that `S * vars = b`. - "inequalities" is a matrix M such that `lb <= M * vars <= ub`. It contains a row for each inequality and as many columns as variables. - "bounds" is a compound matrix [lb ub] containing the lower and upper bounds for the inequality constraints in M. - "variable_fixed" is a boolean vector indicating whether the variable at that index is fixed (`lower bound == upper_bound`) and is thus bounded by an equality constraint. - "variable_bounds" is a compound matrix `[lb ub]` containing the lower and upper bounds for all variables. :rtype: NamedTuple .. rubric:: Notes To accomodate non-zero equalities, the problem will add the variable "const_one" which is a variable that equals one. .. deprecated:: 0.18.1 "DataFrame" option for `array_type` will be replaced with "frame" in future versions. .. py:class:: HistoryManager(**kwargs) Define a base context manager. It records a list of actions to be taken at a later time. This is used to implement context managers that allow temporary changes to a `cobra.core.Model`. .. py:attribute:: _history :value: [] .. py:method:: __call__(operation: Callable[[Any], Any]) -> None Add the corresponding operation to the history stack. :param operation: A function to be called at a later time. :type operation: callable .. py:method:: reset() -> None Trigger executions for all items in the stack in reverse order. .. py:method:: size() -> int Calculate number of operations on the stack. .. py:function:: get_context(obj: cobra.Object) -> Optional[HistoryManager] Search for a context manager. :param obj: The cobra.Object for which to search context manager. :type obj: cobra.Object :returns: HistoryManager instance, or None if no context manager is found. :rtype: HistoryManager or None :raises AttributeError: If no context manager is found. :raises IndexError: If no context manager is found. .. py:function:: resettable(func: Callable[[Any], Any]) -> Callable[[Any], Any] Simplify the context management of simple object attributes. It gets the value of the attribute prior to setting it, and stores a function to set the value to the old value in the `cobra.util.HistoryManager`. :param func: The function to decorate. :type func: callable :returns: The decorated function. :rtype: callable .. py:class:: ProcessPool(processes: Optional[int] = None, initializer: Optional[Callable] = None, initargs: Tuple = (), maxtasksperchild: Optional[int] = None, **kwargs) Define a process pool that handles the Windows platform specially. .. py:attribute:: _filename :value: None .. py:attribute:: _pool .. py:method:: __getattr__(name: str, **kwargs) -> Any Defer attribute access to the pool instance. .. py:method:: __enter__() -> ProcessPool Enable context management. .. py:method:: __exit__(exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[types.TracebackType]) -> Optional[bool] Clean up resources when leaving a context. .. py:method:: close() -> None Close the process pool. Prevent any more tasks from being submitted to the pool. Once all the tasks have been completed, the worker processes will exit. .. py:method:: _clean_up() -> None Remove the dump file if it exists. .. py:data:: OPTLANG_TO_EXCEPTIONS_DICT .. py:exception:: OptimizationError(message) Bases: :py:obj:`Exception` Exception for Optimization issues. .. py:exception:: SolverNotFound Bases: :py:obj:`Exception` A simple Exception when a solver can not be found. .. py:function:: get_context(obj: cobra.Object) -> Optional[HistoryManager] Search for a context manager. :param obj: The cobra.Object for which to search context manager. :type obj: cobra.Object :returns: HistoryManager instance, or None if no context manager is found. :rtype: HistoryManager or None :raises AttributeError: If no context manager is found. :raises IndexError: If no context manager is found. .. py:data:: CONS_VARS .. py:data:: logger .. py:data:: solvers .. py:data:: qp_solvers :value: ['cplex', 'gurobi', 'hybrid'] .. py:data:: has_primals .. py:class:: Components Bases: :py:obj:`NamedTuple` Define an object for adding absolute expressions. .. py:attribute:: variable :type: optlang.interface.Variable .. py:attribute:: upper_constraint :type: optlang.interface.Constraint .. py:attribute:: lower_constraint :type: optlang.interface.Constraint .. py:function:: linear_reaction_coefficients(model: cobra.Model, reactions: Optional[List[cobra.Reaction]] = None) -> Dict[cobra.Reaction, float] Retrieve coefficient for the reactions in a linear objective. :param model: The cobra model defining the linear objective. :type model: cobra.Model :param reactions: An optional list of the reactions to get the coefficients for. By default, all reactions are considered (default None). :type reactions: list of cobra.Reaction, optional :returns: A dictionary where the keys are the reaction objects and the values are the corresponding coefficient. Empty dictionary if there are no linear terms in the objective. :rtype: dict .. py:function:: _valid_atoms(model: cobra.Model, expression: optlang.symbolics.Basic) -> bool Check whether a sympy expression references the correct variables. :param model: The model in which to check for variables. :type model: cobra.Model :param expression: A sympy expression. :type expression: sympy.Basic :returns: True if all referenced variables are contained in model, False otherwise. :rtype: bool .. py:function:: set_objective(model: cobra.Model, value: Union[optlang.interface.Objective, optlang.symbolics.Basic, Dict[cobra.Reaction, float]], additive: bool = False) -> None Set the model objective. :param model: The model to set the objective for. :type model: cobra.Model :param value: If the model objective is linear, then the value can be a new optlang.interface.Objective or a dictionary with linear coefficients where each key is a reaction and the corresponding value is the new coefficient (float). If the objective is non-linear and `additive` is True, then only values of class optlang.interface.Objective, are accepted. :type value: optlang.interface.Objective, optlang.symbolics.Basic, dict :param additive: If True, add the terms to the current objective, otherwise start with an empty objective. :type additive: bool :raises ValueError: If model objective is non-linear and the `value` is a dict. :raises TypeError: If the type of `value` is not one of the accepted ones. .. py:function:: interface_to_str(interface: Union[str, types.ModuleType]) -> str Give a string representation for an optlang interface. :param interface: Full name of the interface in optlang or cobra representation. For instance, 'optlang.glpk_interface' or 'optlang-glpk'. :type interface: str, ModuleType :returns: The name of the interface as a string. :rtype: str .. py:function:: get_solver_name(mip: bool = False, qp: bool = False) -> str Select a solver for a given optimization problem. :param mip: True if the solver requires mixed integer linear programming capabilities. :type mip: bool :param qp: True if the solver requires quadratic programming capabilities. :type qp: bool :returns: The name of the feasible solver. :rtype: str :raises SolverNotFound: If no suitable solver could be found. .. py:function:: choose_solver(model: cobra.Model, solver: Optional[str] = None, qp: bool = False) -> types.ModuleType Choose a solver given a solver name and model. This will choose a solver compatible with the model and required capabilities. Also respects model.solver where it can. :param model: The model for which to choose the solver. :type model: cobra.Model :param solver: The name of the solver to be used (default None). :type solver: str, optional :param qp: True if the solver needs quadratic programming capabilities (default False). :type qp: boolean, optional :returns: Valid solver for the problem. :rtype: optlang.interface :raises SolverNotFound: If no suitable solver could be found. .. py:function:: check_solver(obj) Check whether the chosen solver is valid. Check whether chosen solver is valid and also warn when using a specialized solver. Will return the optlang interface for the requested solver. :param obj: The chosen solver. :type obj: str or optlang.interface or optlang.interface.Model :raises SolverNotFound: If the solver is not valid. .. py:function:: add_cons_vars_to_problem(model: cobra.Model, what: Union[List[CONS_VARS], Tuple[CONS_VARS], Components], **kwargs) -> None Add variables and constraints to a model's solver object. Useful for variables and constraints that can not be expressed with reactions and lower/upper bounds. It will integrate with the model's context manager in order to revert changes upon leaving the context. :param model: The model to which to add the variables and constraints. :type model: cobra.Model :param what: optlang.interface.Constraint The variables and constraints to add to the model. :type what: list or tuple of optlang.interface.Variable or :param \*\*kwargs: Keyword arguments passed to solver's add() method. :type \*\*kwargs: keyword arguments .. py:function:: remove_cons_vars_from_problem(model: cobra.Model, what: Union[List[CONS_VARS], Tuple[CONS_VARS], Components]) -> None Remove variables and constraints from a model's solver object. Useful to temporarily remove variables and constraints from a model's solver object. :param model: The model from which to remove the variables and constraints. :type model: cobra.Model :param what: optlang.interface.Constraint The variables and constraints to remove from the model. :type what: list or tuple of optlang.interface.Variable or .. py:function:: add_absolute_expression(model: cobra.Model, expression: str, name: str = 'abs_var', ub: Optional[float] = None, difference: float = 0.0, add: bool = True) -> Components Add the absolute value of an expression to the model. Also defines a variable for the absolute value that can be used in other objectives or constraints. :param model: The model to which to add the absolute expression. :type model: cobra.Model :param expression: Must be a valid symbolic expression within the model's solver object. The absolute value is applied automatically on the expression. :type expression: str :param name: The name of the newly created variable (default "abs_var"). :type name: str, optional :param ub: The upper bound for the variable (default None). :type ub: positive float, optional :param difference: The difference between the expression and the variable (default 0.0). :type difference: positive float, optional :param add: Whether to add the variable to the model at once (default True). :type add: bool, optional :returns: A named tuple with variable and two constraints (upper_constraint, lower_constraint) describing the new variable and the constraints that assign the absolute value of the expression to it. :rtype: Components .. py:function:: fix_objective_as_constraint(model: cobra.Model, fraction: float = 1.0, bound: Optional[float] = None, name: str = 'fixed_objective_{}') -> float Fix current objective as an additional constraint. When adding constraints to a model, such as done in pFBA which minimizes total flux, these constraints can become too powerful, resulting in solutions that satisfy optimality but sacrifices too much for the original objective function. To avoid that, we can fix the current objective value as a constraint to ignore solutions that give a lower (or higher depending on the optimization direction) objective value than the original model. When done with the model as a context, the modification to the objective will be reverted when exiting that context. :param model: The model to operate on. :type model: cobra.Model :param fraction: The fraction of the optimum the objective is allowed to reach (default 1.0). :type fraction: float, optional :param bound: The bound to use instead of fraction of maximum optimal value. If not None, `fraction` is ignored (default None). :type bound: float, optional :param name: Name of the objective. May contain one "{}" placeholder which is filled with the name of the old objective (default "fixed_objective_{}"). :type name: str, optional :returns: The value of the optimized objective * fraction :rtype: float .. py:function:: check_solver_status(status: str = None, raise_error: bool = False) -> None Perform standard checks on a solver's status. :param status: The status string obtained from the solver (default None). :type status: str, optional :param raise_error: If True, raise error or display warning if False (default False). :type raise_error: bool, optional :rtype: None :Warns: **UserWarning** -- If `status` is not optimal and `raise_error` is set to True. :raises OptimizationError: If `status` is None or is not optimal and `raise_error` is set to True. .. py:function:: assert_optimal(model: cobra.Model, message: str = 'Optimization failed') -> None Assert model solver status is optimal. Do nothing if model solver status is optimal, otherwise throw appropriate exception depending on the status. :param model: The model to check the solver status for. :type model: cobra.Model :param message: Message for the exception if solver status is not optimal (default "Optimization failed"). :type message: str, optional :rtype: None :raises OptimizationError: If solver status is not optimal. .. py:function:: add_lp_feasibility(model: cobra.Model) -> None Add a new objective and variables to ensure a feasible solution. The optimized objective will be zero for a feasible solution and otherwise represent the distance from feasibility (please see [1]_ for more information). :param model: The model whose feasibility is to be tested. :type model: cobra.Model :rtype: None .. rubric:: References .. [1] Gomez, Jose A., Kai Höffner, and Paul I. Barton. “DFBAlab: A Fast and Reliable MATLAB Code for Dynamic Flux Balance Analysis.” BMC Bioinformatics 15, no. 1 (December 18, 2014): 409. https://doi.org/10.1186/s12859-014-0409-8. .. py:function:: add_lexicographic_constraints(model: cobra.Model, objectives: List[cobra.Reaction], objective_direction: Union[str, List[str]] = 'max') -> pandas.Series Successively optimize separate targets in a specific order. For each objective, optimize the model and set the optimal value as a constraint. Proceed in the order of the objectives given. Due to the specific order this is called lexicographic FBA [1]_. This procedure is useful for returning unique solutions for a set of important fluxes. Typically this is applied to exchange fluxes. :param model: The model to be optimized. :type model: cobra.Model :param objectives: A list of reactions (or objectives) in the model for which unique fluxes are to be determined. :type objectives: list of cobra.Reaction :param objective_direction: The desired objective direction for each reaction (if a list) or the objective direction to use for all reactions (default "max"). :type objective_direction: str or list of str, optional :returns: A pandas Series containing the optimized fluxes for each of the given reactions in `objectives`. :rtype: pandas.Series .. rubric:: References .. [1] Gomez, Jose A., Kai Höffner, and Paul I. Barton. “DFBAlab: A Fast and Reliable MATLAB Code for Dynamic Flux Balance Analysis.” BMC Bioinformatics 15, no. 1 (December 18, 2014): 409. https://doi.org/10.1186/s12859-014-0409-8. .. py:function:: format_long_string(string: str, max_length: int = 50) -> str Shorten long string into a small string with ellipsis. :param string: The long string to shorten. :type string: str :param max_length: The maximum length after which to append ellipsis (default 50). :type max_length: int, optional :returns: The shortened string. :rtype: str .. py:class:: AutoVivification Bases: :py:obj:`dict` Implementation of Perl's autovivification feature. .. rubric:: Notes For more information, check https://stackoverflow.com/a/652284/280182 . .. py:method:: __getitem__(item: Any) -> Any Retrieve if item is found, else add it. :param item: The object to look for. :type item: Any :returns: The retrieved object. :rtype: Any .. py:function:: show_versions() -> None Print dependency information.