cobra.medium
============

.. py:module:: cobra.medium


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/cobra/medium/annotations/index
   /autoapi/cobra/medium/boundary_types/index
   /autoapi/cobra/medium/minimal_medium/index


Attributes
----------

.. autoapisummary::

   cobra.medium.sbo_terms


Functions
---------

.. autoapisummary::

   cobra.medium.find_boundary_types
   cobra.medium.find_external_compartment
   cobra.medium.is_boundary_type
   cobra.medium.minimal_medium


Package Contents
----------------

.. py:function:: find_boundary_types(model: cobra.Model, boundary_type: str, external_compartment: Optional[str] = None) -> List[cobra.Reaction]

   Find specific boundary reactions.

   :param model: The cobra model whose boundary reactions are to be found.
   :type model: cobra.Model
   :param boundary_type: Boundary type to check for.
   :type boundary_type: {"exchange", "demand", "sink"}
   :param external_compartment: The ID for the external compartment. If None, it will be detected
                                automatically (default None).
   :type external_compartment: str, optional

   :returns: A list of likely boundary reactions of a user defined type.
   :rtype: list of cobra.Reaction or an empty list


.. py:function:: find_external_compartment(model: cobra.Model) -> str

   Find the external compartment in the model.

   Uses a simple heuristic where the external compartment should be the
   one with the most exchange reactions.

   :param model: The cobra model whose external compartments are to be identified.
   :type model: cobra.Model

   :returns: The putative external compartment.
   :rtype: str

   :raises RuntimeError: If several compartments are similar and thus difficult to identify,
       or, recognized names usually used for external compartment are
       absent.


.. py:function:: is_boundary_type(reaction: cobra.Reaction, boundary_type: str, external_compartment: str) -> bool

   Check whether a reaction is an exchange reaction.

   :param reaction: The reaction to check.
   :type reaction: cobra.Reaction
   :param boundary_type: Boundary type to check for.
   :type boundary_type: {"exchange", "demand", "sink"}
   :param external_compartment: The ID for the external compartment.
   :type external_compartment: str

   :returns: Whether the reaction looks like the requested type. Might be based
             on a heuristic.
   :rtype: bool


.. py:data:: sbo_terms

.. py:function:: minimal_medium(model: cobra.Model, min_objective_value: float = 0.1, exports: bool = False, minimize_components: Union[bool, int] = False, open_exchanges: bool = False) -> Union[pandas.Series, pandas.DataFrame, None]

   Find the minimal growth medium for the `model`.

   Finds the minimal growth medium for the `model` which allows for
   model as well as individual growth. Here, a minimal medium can either
   be the medium requiring the smallest total import flux or the medium
   requiring the least components (ergo ingredients), which will be much
   slower due to being a mixed integer problem (MIP).

   :param model: The model to modify.
   :type model: cobra.model
   :param min_objective_value: The minimum growth rate (objective) that has to be achieved
                               (default 0.1).
   :type min_objective_value: float > 0 or array-like object, optional
   :param exports: Whether to include export fluxes in the returned medium.
                   Defaults to False which will only return import fluxes
                   (default False).
   :type exports: bool, optional
   :param minimize_components: Whether to minimize the number of components instead of the total
                               import flux. Might be more intuitive if set to True, but may also
                               be slow to calculate for large communities. If set to a number `n`
                               will return up to `n` alternative solutions all with the same
                               number of components (default False).
   :type minimize_components: bool or int > 0, optional
   :param open_exchanges: Whether to ignore currently set bounds and make all exchange
                          reactions in the `model` possible. If set to a `number`, all
                          exchange reactions will be opened with (-`number`, `number`) as
                          bounds (default False).
   :type open_exchanges: bool or number, optional

   :returns: A pandas.Series giving the import flux for each required import
             reaction and (optionally) the associated export fluxes. All exchange
             fluxes are oriented into the import reaction e.g. positive fluxes
             denote imports and negative fluxes exports. If `minimize_components`
             is a number larger than 1, may return a pandas.DataFrame where each
             column is a minimal medium. Returns None, if the minimization is
             infeasible (for instance if min_growth > maximum growth rate).
   :rtype: pandas.Series, pandas.DataFrame or None

   .. rubric:: Notes

   Due to numerical issues, the `minimize_components` option will usually
   only minimize the number of "large" import fluxes. Specifically, the
   detection limit is given by ``integrality_tolerance * max_bound`` where
   ``max_bound`` is the largest bound on an import reaction. Thus, if you
   are interested in small import fluxes as well you may have to adjust the
   solver tolerance at first with `model.tolerance = 1e-7` for instance.
   However, this will be *very* slow for large models especially with GLPK.