:mod:`paramonte.vis.GridPlot` ============================= .. py:module:: paramonte.vis.GridPlot Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: paramonte.vis.GridPlot.GridPlot Functions ~~~~~~~~~ .. autoapisummary:: paramonte.vis.GridPlot._hide_current_axis paramonte.vis.GridPlot._show_current_axis .. data:: Struct .. data:: newline .. py:class:: GridPlot(plotType, dataFrame=None, methodName='ParaMonte', reportEnabled=True, resetPlot=None) Bases: :class:`paramonte.vis._BasePlot.BasePlot` This is the GridPlot class for generating instances of histogram and contour figures in two and three dimensions based on a wide range of plotting tools from the matplotlib, seaborn, and other Python libraries. Normally, the public users are not supposed to use this class directly, although they can for the purposes other than plotting the ParaMonte simulation files. **Parameters** plotType A string indicating the name of the plot to be constructed. dataFrame (optional) A pandas dataFrame whose data will be plotted. methodName (optional) The name of the ParaMonte sample requesting the BasePlot. reportEnabled (optional) A boolean whose value indicates whether guidelines should be printed in the standard output. resetPlot (optional) A function that resets the properties of the plot as desired from outside. If provided, a pointer to this function will be saved for future internal usage. **Attributes** All of the parameters described above, are implicitly stored in the object. columns An attribute that determines the columns of dataFrame to be visualized. It can have three forms: 1. A list of column indices in dataFrame. 2. A list of column names in dataFrame.columns. 3. A ``range(start,stop,step)`` of column indices. Examples: 1. ``xcolumns = [0,1,4,3]`` 2. ``xcolumns = ["SampleLogFunc","SampleVariable1"]`` 3. ``xcolumns = range(17,7,-2)`` The default behavior includes up to 5 columns of the dataFrame. ccolumn A string or integer that determines the column of the dataFrame to serve as the color-values corresponding to each point in the plot. Examples: 1. ``ccolumn = 7`` 2. ``ccolumn = "SampleLogFunc"`` 3. ``ccolumn = None`` **NOTE** The value of ``ccolumns`` has precedence over all other color properties of individual plotting tools, unless ``ccolumns = None``. For example, any value of the ``c`` component of the ``scatter.kws`` component of the ``LineScatterPlot`` object will be overridden by the specified value for ``ccolumns``. rows An attribute that determines the rows of dataFrame to be visualized. It can be either: 1. A ``range(start,stop,step)``, or, 2. A list of row indices in dataFrame.index. Examples: 1. ``rows = range(17,7,-2)`` 2. ``rows = [i for i in range(7,17)]`` The default behavior includes all rows of the dataFrame. set A structure with two attributes: enabled A boolean indicating whether a call to the ``set()`` function of the seaborn library should be made or not. kws A structure whose components are directly passed as keyword arguments to the ``set()`` function. Example usage: .. code-block:: python set.kws.style = "darkgrid" **NOTE** If a desired property is missing among the ``kws`` attributes, simply add the field and its value to the component. axes (available only in 1D and 2D plots) A structure with one attribute: kws A structure whose components are directly passed as keyword arguments to the ``gca()`` function of the matplotlib library. Example usage: .. code-block:: python axes.kws.facecolor = "w" **NOTE** If a desired property is missing among the ``kws`` attributes, simply add the field and its value to the component. figure A structure with two attributes: enabled A boolean indicating whether a call to the ``figure()`` function of the matplotlib library should be made or not. If a call is made, a new figure will be generated. Otherwise, the current active figure will be used. kws A structure whose components are directly passed as keyword arguments to the ``figure()`` function of the matplotlib library. Example usage: .. code-block:: python figure.kws.facecolor = "w" **NOTE** If a desired property is missing among the ``kws`` attributes, simply add the field and its value to the component. pairgrid A structure with one attribute: kws A structure whose components are directly passed as keyword arguments to the ``PairGrid()`` class of the seaborn library to generate a pairgrid. Example usage: .. code-block:: python pairgrid.kws.dropna = True **NOTE** Passing some keywords, like ``corner`` attribute, to the PairGrid will cause potential conflicts with other attributes of ParaMonte's GridPlot. Use this attribute with caution. That said, if a desired property is missing among the ``kws`` attributes, simply add the field and its value to the component. colorbar (exists only for plots that require colorbar) A structure with two attributes: enabled A boolean indicating whether a call to the ``colorbar()`` function of the matplotlib library should be made or not. If a call is made, a new figure will be generated. Otherwise, the current active figure will be used. kws A structure whose components are directly passed as keyword arguments to the ``colorbar()`` function of the matplotlib library. **NOTE** If a desired property is missing among the ``kws`` attributes, simply add the field and its value to the component. A colorbar will be added to a plot only if a color-mappings is requested in the plot. plotType A structure with three attributes: upper A structure whose components determine what plots can and should be added to the upper corner of the grid plot. lower A structure whose components determine what plots can and should be added to the lower corner of the grid plot. diag A structure whose components determine what plots can and should be added to the diagonal of the grid plot. Each of the above structures has three components: enabled A boolean that determines if the subplots in the corresponding section of the grid plot should be added or not. names A list of strings that represent the types of plots that can be added to the corresponding section of the grid plot. value A string whose value can be one of the elements of the ``names`` attribute explained in the above. It determines the type of the subplot to be added to the corresponding section of the grid plot. Example usage: .. code-block:: python plotType.upper.enabled = False # no upper corner plots plotType.lower.value = "scatter" # add scatter to lower layout A structure whose components are directly passed to the corresponding plotting tools of the ParaMonte library to draw the corresponding subplots, if they are activated. Example usage: .. code-block:: python layout.contour.contour.kws.colors = "blue" currentFig A structure whose attributes are the outputs of various plotting tools used to make the current figure. These include the handle to the current figure, the handle to the current axes in the plot, the handle to the colorbar (if any exists), and other Python plotting tools used to make to generate the figure. **Returns** self An object of class ``GridPlot``. --------------------------------------------------------------------------- .. method:: _reset(self) .. method:: __call__(self, reself: tp.Optional[bool] = False, **kwargs) Call the ``make()`` method of the current instance of the class. **Parameters** Any arguments that can be passed to the ``make()`` method of the plot object. **Returns** Any return value from the ``make()`` method of the plot object. .. method:: make(self, reself: tp.Optional[bool] = False, **kwargs) Generate a grid plot from the selected columns of the object's dataFrame. **Parameters** reself A logical variable. If ``True``, an instance of the object will be returned to the calling routine upon exit. The default value is ``False``. **Returns** The object self if ``reself = True`` otherwise, ``None``. However, this method causes side-effects by manipulating the existing attributes of the object. .. method:: _addColorBar(self) .. method:: hide(self, part='all') Hides the requested part of the grid plot. **Parameters** part A string with the following possible values: "lower" hides the lower triangle of the grid plot. "upper" hides the upper triangle of the grid plot. "diag" hides the diagonal of the grid plot. "all" hides all grid plots and the colorbar. "colorbar" hides the colorbar of the grid plot. The string can also be a mix of the above keywords, separated by the ``+`` sign or some other delimiter. For example, ``"lower+upper+colorbar"`` **Returns** None .. method:: show(self, part='all') Shows the requested part of the grid plot. **Parameters** part a string with the following possible values: "lower" shows the lower triangle of the grid plot. "upper" shows the lower triangle of the grid plot. "diag" shows the diagonal of the grid plot. "all" shows all grid plots. "colorbar" shows the colorbar of the grid plot. The string can also be a mix of the above keywords, separated by the ``+`` sign or some other delimiter. For example, ``"lower+upper+colorbar"`` **Returns** None .. method:: addTarget(self, value: tp.Union[np.ndarray, tp.List[float], tp.Tuple[float]] = None) Call the target callable associated with each element of currentFig.subplotGrid of the GridPlot object to add target points and/or lines to all plots of the ``GridPlot`` figure. This method is supposed to be called only after a grid plot has been generated. **Parameters** value (optional) A numpy array, or list, or tuple whose length equals the number of columns/rows of the grid plot, each element of which represents the target value associated with the corresponding variable on the ``x`` axis of the plot, from the left to the right. Alternatively, ``value`` can be a string with the following possible value: "mode" The variable values corresponding to the mode of the "SampleLogFunc" column of the input dataFrame will be used. If no "SampleLogFunc" columns name exists in the input dataFrame, an exception will be raised. This is the **default value** for the input variable ``value``. "mean" The variable values corresponding to the mode of the "SampleLogFunc" column of the input dataFrame will be used. If no "SampleLogFunc" columns name exists in the input dataFrame, an exception will be raised. If not provided, the default will be set to the state (coordinates) of the mode of the "SampleLogFunc" column in the input dataFrame to the object. This would work only when the input dataFrame is the contents of a ParaMonte output chain or sample file. **Returns** None. However, this method causes side-effects by manipulating the existing attributes of the ``Target`` objects in ``currentFig.subplotGrid`` of the GridPlot object. .. method:: _getDocString(self) .. method:: helpme(self, topic=None) Print the documentation for the input string topic. If the topic does not exist, the documentation for the object will be printed. **Parameters** topic (optional) A string containing the name of the object for which help is needed. **Returns** None **Example** .. code-block:: python :linenos: helpme() helpme("make") helpme("helpme") helpme("getLogLinSpace") .. function:: _hide_current_axis(*args, **kwds) .. function:: _show_current_axis(*args, **kwds)