cobra.flux_analysis.room
========================

.. py:module:: cobra.flux_analysis.room

.. autoapi-nested-parse::

   Provide regulatory on/off minimization (ROOM).



Functions
---------

.. autoapisummary::

   cobra.flux_analysis.room.room
   cobra.flux_analysis.room.add_room


Module Contents
---------------

.. py:function:: room(model: cobra.Model, solution: Optional[cobra.Solution] = None, linear: bool = False, delta: float = 0.03, epsilon: float = 0.001) -> cobra.Solution

   Compute a solution based on regulatory on/off minimization (ROOM).

   Compute a new flux distribution that minimizes the number of active
   reactions needed to accommodate a previous reference solution.
   Regulatory on/off minimization (ROOM) is generally used to assess the
   impact of knock-outs. Thus, the typical usage is to provide a wild-type
   flux distribution as reference and a `model` in knock-out state.

   :param model: The model state to compute a ROOM-based solution for.
   :type model: cobra.Model
   :param solution: A (wild-type) reference solution (default None).
   :type solution: cobra.Solution, optional
   :param linear: Whether to use the linear ROOM formulation or not (default False).
   :type linear: bool, optional
   :param delta: The relative tolerance range (additive) (default 0.03).
   :type delta: float, optional
   :param epsilon: The absolute tolerance range (multiplicative) (default 0.001).
   :type epsilon: float, optional

   :returns: A flux distribution with minimal active reaction changes compared to
             the reference.
   :rtype: cobra.Solution

   .. seealso::

      :py:obj:`add_room`
          add ROOM constraints and objective


.. py:function:: add_room(model: cobra.Model, solution: Optional[cobra.Solution] = None, linear: bool = False, delta: float = 0.03, epsilon: float = 0.001) -> None

   Add constraints and objective for ROOM.

   This function adds variables and constraints for applying regulatory
   on/off minimization (ROOM) to the model.

   :param model: The model to add ROOM constraints and objective to.
   :type model: cobra.Model
   :param solution: A previous solution to use as a reference. If no solution is given,
                    one will be computed using pFBA (default None).
   :type solution: cobra.Solution, optional
   :param linear: Whether to use the linear ROOM formulation or not (default False).
   :type linear: bool, optional
   :param delta: The relative tolerance range which is additive in nature
                 (default 0.03).
   :type delta: float, optional
   :param epsilon: The absolute range of tolerance which is multiplicative
                   (default 0.001).
   :type epsilon: float, optional

   .. rubric:: Notes

   The formulation used here is the same as stated in the original paper [1]_.
   The mathematical expression is given below:

   minimize: \sum_{i=1}^m y^i
   s.t.    : Sv = 0
             v_min \le v \le v_max
             v_j = 0
             j \in A
             for 1 \le i \le m
             v_i - y_i(v_{max,i} - w_i^u) \le w_i^u        (1)
             v_i - y_i(v_{min,i} - w_i^l) \le w_i^l        (2)
             y_i \in {0,1}                                 (3)
             w_i^u = w_i + \delta|w_i| + \epsilon
             w_i^l = w_i - \delta|w_i| - \epsilon

   So, for the linear version of the ROOM , constraint (3) is relaxed to
   0 \le y_i \le 1.

   .. seealso::

      :py:obj:`pfba`
          parsimonious FBA

   .. rubric:: References

   .. [1] Tomer Shlomi, Omer Berkman and Eytan Ruppin, "Regulatory on/off
    minimization of metabolic flux changes after genetic perturbations",
    PNAS 2005 102 (21) 7695-7700; doi:10.1073/pnas.0406346102