:orphan:

:py:mod:`cowpatch.layout_elements`
==================================

.. py:module:: cowpatch.layout_elements


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

Classes
~~~~~~~

.. autoapisummary::

   cowpatch.layout_elements.layout
   cowpatch.layout_elements.area




.. py:class:: layout(ncol=None, nrow=None, byrow=None, rel_widths=None, rel_heights=None, design=None)

   layout class to store information about arangement of patches found
   in `cow.patch`.

   :param ncol: Integer for the number of columns to arrange the the patches in.
                The default is None (which avoids conflicts if a value for
                `design` is provided). If ``ncol`` is None but ``nrow`` is not,
                then ``ncol`` will default to the minimum number of columns to
                make sure that all patches can be visualized.
   :type ncol: integer
   :param nrow: Integer for the number of rows to arrange the the patches in.
                The default is None (which avoids conflicts if a value for
                ``design`` is provided). If ``nrow`` is None but ``ncol`` is not,
                then ``nrow`` will default to the minimum number of rows to make
                sure that all patches can be visualized.
   :type nrow: integer
   :param byrow: If ``ncol`` and/or ``nrow`` is included, then this boolean
                 indicates if the patches should be ordered by row (default if
                 ``byrow`` is None or when parameter is ``True``) or by column (if
                 ``byrow`` was ``False``).
   :type byrow: boolean
   :param design: Specification of the location of each patch in the arrangement.
                  Can either be a float numpy array with integers between 0 and
                  the number of patches to arrange, or a text string that captures
                  similar ideas to the array approach but uses capital alphabetical
                  characters (A-Z) to indicate each figure. More information is in
                  Notes.
   :type design: np.array (float based) or str
   :param rel_widths: Numerical vector of relative columns widths. This not required,
                      the default would be ``np.ones(ncol)`` or
                      ``np.ones(design.shape[0])``. Note that this is a relative sizing
                      and the values are only required to be non-negative, non-zero
                      values, for example ``[1,2]`` would would make the first column
                      twice as wide as the second column.
   :type rel_widths: list, np vector or tuple
   :param rel_heights: Numerical vector of relative row heights. This not required,
                       the default would be ``np.ones(nrow)`` or
                       ``np.ones(design.shape[1])``. Note that this is a relative sizing
                       and the values are only required to be non-negative, non-zero
                       values, for example ``[1,2]`` would would make the first row twice
                       as tall as the second row.
   :type rel_heights: list or tuple

   .. rubric:: Notes

   *Design*

   The ``design`` parameter expects specific input.

   1. If the ``design`` is input as a numpy array, we expect it to have
   integers only (0 to # patches-1). It is allowed to have ``np.nan``
   values if certain "squares" of the  layout are not covered by others
   (the covering is defined by the value ordering). Note that we won't
   check for overlap and ``np.nan`` is not enforced if another patches'
   relative (min-x,min-y) and (max-x, max-y) define a box over that
   ``np.nan``'s area.

   An example of a design of the numpy array form could look like

   >>> my_np_design = np.array([[1,1,2],
   ...                          [3,3,2],
   ...                          [3,3,np.nan]])

   2. if the ``design`` parameter takes in a string, we expect it to have
   a structure such that each line (pre ``\\n``) contains the same number
   of characters, and these characters must come from the first
   (number of patches) capital alphabetical characters or the ``\#`` or
   ``.`` sign to indicate an empty square. Similar arguments w.r.t.
   overlap and the lack of real enforcement for empty squares applies
   (as in 1.).

   An example of a design of the string form could look like

   >>> my_str_design = """
   ... AAB
   ... CCB
   ... CC\#
   ... """

   or

   >>> my_str_design = """
   ... AAB
   ... CCB
   ... CC.
   ... """

   See the `Layout guide`_ for more detailed examples of functionality.

   .. _Layout guide: https://benjaminleroy.github.io/cowpatch/guides/Layout.html

   *Similarities to our `R` cousins:*

   This layout function is similar to `patchwork\:\:plot_layout <https://patchwork.data-imaginist.com/reference/plot_layout.html>`_
   (with a special node to ``design`` parameter) and helps perform similar
   ideas to `gridExtra\:\:arrangeGrob <https://cran.r-project.org/web/packages/gridExtra/vignettes/arrangeGrob.html>`_'s
   ``layout_matrix`` parameter, and `cowplot\:\:plot_grid <https://wilkelab.org/cowplot/reference/plot_grid.html>`_'s
   ``rel_widths`` and ``rel_heights`` parameters.

   .. rubric:: Examples

   >>> # Necessary libraries for example
   >>> import numpy as np
   >>> import cowpatch as cow
   >>> import plotnine as p9
   >>> import plotnine.data as p9_data

   >>> g0 = p9.ggplot(p9_data.mpg) +\
   ...     p9.geom_bar(p9.aes(x="hwy")) +\
   ...     p9.labs(title = 'Plot 0')
   >>> g1 = p9.ggplot(p9_data.mpg) +\
   ...     p9.geom_point(p9.aes(x="hwy", y = "displ")) +\
   ...     p9.labs(title = 'Plot 1')
   >>> g2 = p9.ggplot(p9_data.mpg) +\
   ...     p9.geom_point(p9.aes(x="hwy", y = "displ", color="class")) +\
   ...     p9.labs(title = 'Plot 2')
   >>> g3 = p9.ggplot(p9_data.mpg[p9_data.mpg["class"].isin(["compact",
   ...                                                      "suv",
   ...                                                      "pickup"])]) +\
   ...     p9.geom_histogram(p9.aes(x="hwy"),bins=10) +\
   ...     p9.facet_wrap("class")

   >>> # design matrix
   >>> vis_obj = cow.patch(g1,g2,g3)
   >>> vis_obj += cow.layout(design = np.array([[0,1],
   ...                                          [2,2]]))
   >>> vis_obj.show()

   >>> # design string
   >>> vis_obj2 = cow.patch(g1,g2,g3)
   >>> vis_obj2 += cow.layout(design = """
   ...                                 AB
   ...                                 CC
   ...                                 """)
   >>> vis_obj2.show()

   >>> # nrow, ncol, byrow
   >>> vis_obj3 = cow.patch(g0,g1,g2,g3)
   >>> vis_obj3 += cow.layout(nrow=2, byrow=False)
   >>> vis_obj3.show()

   >>> # rel_widths/heights
   >>> vis_obj = cow.patch(g1,g2,g3)
   >>> vis_obj += cow.layout(design = np.array([[0,1],
   ...                                          [2,2]]),
   ...                       rel_widths = np.array([1,2]))
   >>> vis_obj.show()

   .. seealso::

      :obj:`area`
          object class that helps ``layout`` define where plots will go in the arangement

      :obj:`patch`
          fundamental object class which is combined with ``layout`` to defin the overall arangement of plots

   .. py:attribute:: design
      

      defines underlying ``design`` attribute (potentially defined relative to a
      ``cow.patch`` object if certain structure are not extremely specific.


.. py:class:: area(x_left, y_top, width, height, _type)

   object that stores information about what area a ``patch`` will fill

   :param x_left: scalar of where the left-most point of the patch is located (impacted
                  by the ``_type`` parameter)
   :type x_left: float
   :param y_top: scalar of where the top-most point of the patch is located (impacted
                 by the ``_type`` parameter)
   :type y_top: float
   :param width: scalar of the width of the patch (impacted by the ``_type``
                 parameter)
   :type width: float
   :param height: scalar of the height of the patch (impacted by the ``_type``
                  parameter)
   :type height: float
   :param _type: describes how the parameters are stored. See Notes for more
                 information between the options.
   :type _type: str {"design", "relative", "pt"}

   .. rubric:: Notes

   These objects provide structural information about where in the overall
   arangement individual plots / sub arangments lie.

   The ``_type`` parameter informs how to understand the other parameters:

   1. "design" means that the values are w.r.t. to a design matrix
   relative to the `layout` class, and values are relative to the rows
   and columns units.

   2. "relative" means the values are defined relative to the full size of
   the canvas and taking values between 0-1 (inclusive).

   3. "pt" means that values are defined relative to point values

   .. seealso::

      :obj:`layout`
          object that incorporates multiple area definitions to define layouts.

   .. py:method:: pt(width_pt=None, height_pt=None, rel_widths=None, rel_heights=None)

      Translates area object to ``_type`` = "pt"

      :param width_pt: width in points (required if ``_type`` is not "pt")
      :type width_pt: float
      :param height_pt: height in points (required if ``_type`` is not "pt")
      :type height_pt: float
      :param rel_widths: list of relative widths of each column of the layout matrix
                         (required if ``_type`` is "design")
      :type rel_widths: np.array (vector)
      :param rel_heights: list of relative heights of each row of the layout matrix
                          (required if ``_type`` is "design")
      :type rel_heights: np.array (vector)

      :returns: area object of ``_type`` = "pt"
      :rtype: area object