cobra.flux_analysis.moma
========================

.. py:module:: cobra.flux_analysis.moma

.. autoapi-nested-parse::

   Provide minimization of metabolic adjustment (MOMA).



Functions
---------

.. autoapisummary::

   cobra.flux_analysis.moma.moma
   cobra.flux_analysis.moma.add_moma


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

.. py:function:: moma(model: cobra.core.Model, solution: Optional[cobra.core.Solution] = None, linear: bool = True) -> cobra.core.Solution

   Compute a single solution based on (linear) MOMA.

   Compute a new flux distribution that is at a minimal distance to a
   previous reference solution `solution`. Minimization of metabolic
   adjustment (MOMA) 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 MOMA-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 MOMA formulation or not (default True).
   :type linear: bool, optional

   :returns: A flux distribution that is at a minimal distance compared to the
             reference solution.
   :rtype: cobra.Solution

   .. seealso::

      :py:obj:`add_moma`
          add MOMA constraints and objective


.. py:function:: add_moma(model: cobra.core.Model, solution: Optional[cobra.core.Solution] = None, linear: bool = True) -> None

   Add MOMA constraints and objective representing to the `model`.

   This adds variables and constraints for the minimization of metabolic
   adjustment (MOMA) to the model.

   :param model: The model to add MOMA 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 MOMA formulation or not (default True).
   :type linear: bool, optional

   .. rubric:: Notes

   In the original MOMA [1]_ specification, one looks for the flux
   distribution of the deletion (v^d) closest to the fluxes without the
   deletion (v).
   In math this means:

   minimize: \sum_i (v^d_i - v_i)^2
   s.t.    : Sv^d = 0
             lb_i \le v^d_i \le ub_i

   Here, we use a variable transformation v^t := v^d_i - v_i. Substituting
   and using the fact that Sv = 0 gives:

   minimize: \sum_i (v^t_i)^2
   s.t.    : Sv^d = 0
             v^t = v^d_i - v_i
             lb_i \le v^d_i \le ub_i

   So, basically we just re-center the flux space at the old solution and
   then find the flux distribution closest to the new zero (center). This
   is the same strategy as used in cameo.

   In the case of linear MOMA [2]_, we instead minimize \sum_i abs(v^t_i).
   The linear MOMA is typically significantly faster. Also, quadratic MOMA
   tends to give flux distributions in which all fluxes deviate from the
   reference fluxes a little bit whereas linear MOMA tends to give flux
   distributions where the majority of fluxes are the same reference with
   few fluxes deviating a lot (typical effect of L2 norm vs L1 norm).

   The former objective function is saved in the optlang solver interface as
   ``"moma_old_objective"`` and this can be used to immediately extract the
   value of the former objective after MOMA optimization.

   .. seealso::

      :py:obj:`pfba`
          parsimonious FBA

   .. rubric:: References

   .. [1] Segrè, Daniel, Dennis Vitkup, and George M. Church. “Analysis of
          Optimality in Natural and Perturbed Metabolic Networks.”
          Proceedings of the National Academy of Sciences 99, no. 23
          (November 12, 2002): 15112. https://doi.org/10.1073/pnas.232349399.
   .. [2] Becker, Scott A, Adam M Feist, Monica L Mo, Gregory Hannum,
          Bernhard Ø Palsson, and Markus J Herrgard. “Quantitative
          Prediction of Cellular Metabolism with Constraint-Based Models:
          The COBRA Toolbox.” Nature Protocols 2 (March 29, 2007): 727.