micom.viz
=========

.. py:module:: micom.viz

.. autoapi-nested-parse::

   Init file for MICOM Visualization.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/micom/viz/association/index
   /autoapi/micom/viz/core/index
   /autoapi/micom/viz/exchanges/index
   /autoapi/micom/viz/growth/index
   /autoapi/micom/viz/interactions/index
   /autoapi/micom/viz/tradeoff/index


Classes
-------

.. autoapisummary::

   micom.viz.Visualization


Functions
---------

.. autoapisummary::

   micom.viz.plot_exchanges_per_sample
   micom.viz.plot_exchanges_per_taxon
   micom.viz.plot_growth
   micom.viz.plot_focal_interactions
   micom.viz.plot_mes
   micom.viz.plot_tradeoff


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

.. py:class:: Visualization(filename, data, template)

   Bases: :py:obj:`object`


   A visualization object.

   .. attribute:: filename

      The filename of trhe saved visualization.

      :type: str

   .. attribute:: data

      The data used to create the Visualization.

      :type: dict

   .. attribute:: template

      The jinja template used to render the visualization.

      :type: jinja2.Template


   .. py:attribute:: filename


   .. py:attribute:: data


   .. py:attribute:: template


   .. py:method:: view()

      Open the visualization in a browser.

      :param None.:

      :rtype: nothing



   .. py:method:: save(**kwargs)

      Render and and save the visualization.



.. py:function:: plot_exchanges_per_sample(results, filename='sample_exchanges_%s.html' % datetime.now().strftime('%Y%m%d'), direction='import', cluster=True) -> None

   Plot the per sample exchange fluxes.

   :param results: The results returned by the `grow` workflow.
   :type results: micom.workflows.GrowthResults
   :param filename: The HTML file where the visualization will be saved.
   :type filename: str
   :param direction: The direction of fluxes to plot.
   :type direction: str either "import" or "export"
   :param cluster: Whether to reorder samples so that samples with similar exchange
                   fluxes are close to another.
   :type cluster: bool

   :returns: A MICOM visualization. Can be served with `viz.serve`.
   :rtype: Visualization


.. py:function:: plot_exchanges_per_taxon(results, filename='taxon_exchanges_%s.html' % datetime.now().strftime('%Y%m%d'), direction='import', use_total_flux=False, **tsne_args) -> None

   Plot the exchange fluxes per taxon.

   :param results: The exchanges returned by the `grow` workflow.
   :type results: micom.workflows.GrowthResults
   :param filename: The HTML file where the visualization will be saved.
   :type filename: str
   :param direction: The direction of fluxes to plot.
   :type direction: str either "import" or "export"
   :param use_total_fluxes: Whether to use fluxes normalized to 1gDW of bacteria or the total flux.
   :type use_total_fluxes: bool
   :param tsne_args: Additional arguments passed to TSNE.
   :type tsne_args: dict

   :returns: A MICOM visualization. Can be served with `viz.serve`.
   :rtype: Visualization


.. py:function:: plot_growth(results, filename='growth_rates_%s.html' % datetime.now().strftime('%Y%m%d'), tolerance=1e-06)

   Plot the taxa growth rates.

   :param results: The results returned by the `grow` workflow.
   :type results: micom.workflows.GrowthResults
   :param filename: The HTML file where the visualization will be saved.
   :type filename: str
   :param tolerance: Smallest growth rate that will be considered. Everything lower will be
                     considered not growing.
   :type tolerance: float

   :returns: A MICOM visualization. Can be served with `viz.serve`.
   :rtype: Visualization


.. py:function:: plot_focal_interactions(results: micom.workflows.GrowthResults, taxon: str, filename: str = 'focal_interactions_%s.html' % datetime.now().strftime('%Y%m%d'), kind: str = 'mass') -> None

   Plot metabolic interactions between a focal taxa and all other taxa.

   This will visualize metabolic interaction between a taxon of interest (focal taxon)
   and all other taxa across all samples.

   :param results: The results returned by the `grow` workflow.
   :type results: micom.workflows.GrowthResults
   :param taxon: The focal taxon to use as a reference. Must be one of the taxa appearing
                 in `results.growth_rates.taxon`.
   :type taxon: str
   :param filename: The HTML file where the visualization will be saved.
   :type filename: str
   :param kind: Which kind of flux to use. Either
                - "flux": molar flux of a metabolite
                - "mass" (default): the mass flux (flux normalized by molecular weight)
                - "C": carbon flux
                - "N": nitrogen flux
   :type kind: str

   :returns: A MICOM visualization. Can be served with `viz.serve`.
   :rtype: Visualization


.. py:function:: plot_mes(results: micom.workflows.GrowthResults, filename: str = 'mes_%s.html' % datetime.now().strftime('%Y%m%d'), groups: pandas.Series = None, prevalence: float = 0.5) -> None

   Plot metabolic interactions between a focal taxa and all other taxa.

       This will plot the metabolic exchange score across samples and metabolites.
       The metabolic exchange score (MES) is defined as the geometric mean of the
       number of producers and consumers for a given metabolite in a sample.

       $$
       MES = 2\cdot
   rac{|p||c|}{|p| + |c|}
       $$

       Parameters
       ----------
       results : micom.workflows.GrowthResults
           The results returned by the `grow` workflow.
       filename : str
           The HTML file where the visualization will be saved.
       groups : pandas.Series
           Additional metadata to stratify MES score. The index must correspond to the
           `sample_id` in the results and values must be categorical. The `.name` attribute
           will be used to name the groups.
       prevalence : float in [0, 1]
           In what proportion of samples the metabolite has to have a non-zero MES to
           be shown on the plots. Can be used to show only very commonly exchanged
           metabolites.

       Notes
       -----
       The CSV files will always include all MES scores independent of the prevalence
       filter which is only used for visualization.

       Returns
       -------
       Visualization
           A MICOM visualization. Can be served with `viz.serve`.



.. py:function:: plot_tradeoff(tradeoff_rates, filename='tradeoff_%s.html' % datetime.now().strftime('%Y%m%d'), tolerance=1e-06)

   Plot diagnostics for varying tradeoff values.

   :param tradeoff_rates: The growth rates returned by the `tradeoff` workflow.
   :type tradeoff_rates: pandas.DataFrame
   :param filename: The HTML file where the visualization will be saved.
   :type filename: str
   :param tolerance: Smallest growth rate that will be considered. Everything lower will be
                     considered not growing.
   :type tolerance: float

   :returns: A MICOM visualization. Can be served with `viz.serve`.
   :rtype: Visualization