:py:mod:`pyloggrid.Libs.plotLib`
================================

.. py:module:: pyloggrid.Libs.plotLib

.. autoapi-nested-parse::

   Utilities for fast plotting



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


Functions
~~~~~~~~~

.. autoapisummary::

   pyloggrid.Libs.plotLib.initFormat
   pyloggrid.Libs.plotLib.pltshowm
   pyloggrid.Libs.plotLib.labels
   pyloggrid.Libs.plotLib.scatter
   pyloggrid.Libs.plotLib.plot2axes
   pyloggrid.Libs.plotLib.plot2axesX
   pyloggrid.Libs.plotLib._save_animation_from_slider
   pyloggrid.Libs.plotLib.dec_enable_slider_save
   pyloggrid.Libs.plotLib.interactive_spectrum
   pyloggrid.Libs.plotLib.interactive_3D_logplot_by_z
   pyloggrid.Libs.plotLib.interactive_grid_imshow
   pyloggrid.Libs.plotLib.interactive_grid_3Dslice
   pyloggrid.Libs.plotLib.interactive_3D_logplot_positive
   pyloggrid.Libs.plotLib.rand_cmap



.. py:function:: initFormat(size: float = 1, txtsize: float = None, rcParams: dict = None) -> None

   Sets up pyplot formatting for scientific publications.

   :param size: the figure's size relative to the default one
   :param txtsize: scaling for the figure's fonts, if not set defaults to ``size``
   :param rcParams: parameters to append to :attr:`matplotlib.rcParams`


.. py:function:: pltshowm(full: bool = True, save: str = None, legend: bool = True, compact: bool = True, tight: bool = False) -> None

   Display the pyplot figure maximized.

   :param legend: if ``False``, do not add a legend
   :param save: if specified, save path for the figure
   :param full: if ``False``, doe not go fullscreen
   :param compact: if ``True``, use ``plt.tight_layout``
   :param tight: if ``True``, autoscale with tight boundaries


.. py:function:: labels(xlabel: str = '', ylabel: str = '', title: str = '', ax: Any = None) -> None

   Add labels and title to an axis.

   :param xlabel:
   :param ylabel:
   :param title:
   :param ax: if specified, the axis on which to add the labels; defaults to the current axis


.. py:function:: scatter(ax=None, *args, **kwargs) -> Any

   Plot a scatter plot using ``plot()`` instead of ``scatter()``.

   (not handled the same way, e.g. zindex)

   :param ax: the axis to use, defaults to


.. py:function:: plot2axes() -> tuple[matplotlib.figure.Figure, Any, Any]

   Create a plot with left and right axis.

   Axes are set to `Any` since the real class is hidden in ``mpl.axes._subplots``.

   :returns: ``figure, ax1, ax2``


.. py:function:: plot2axesX() -> tuple[matplotlib.figure.Figure, Any, Any]

   plot with bottom and top axis.

   Axes are set to `Any` since the real class is hidden in ``mpl.axes._subplots``.


.. py:function:: _save_animation_from_slider(slider: matplotlib.widgets.Slider, save: str, temp_dir: str, N: int = 100) -> None

   Save a matplotlib graph with a slider as an animation.

   :param slider: the slider object
   :param save: the output file name
   :param temp_dir: where to store the intermediate images
   :param N: number of frames


.. py:function:: dec_enable_slider_save(f: Callable) -> Callable

   Decorator to save an animation from a slider graph.

   This adds two arguments to the decorated function, ``save`` and ``temp_path``, which if supplied are forwarded to :func:`_save_animation_from_slider`.


.. py:function:: interactive_spectrum(ts: pyloggrid.Libs.singlethread_numpy.np.ndarray, ks: pyloggrid.Libs.singlethread_numpy.np.ndarray, spectra: dict[str, pyloggrid.Libs.singlethread_numpy.np.ndarray], quantities: dict[str, pyloggrid.Libs.singlethread_numpy.np.ndarray]) -> tuple[matplotlib.widgets.Slider, Any, Any]

   An interactive spectrum + arbitrary time-dependant quantities.

   .. warning:: As for all interactive functions, the returned val must be assigned, ex via ``_ = my_interactive_function(...)``

   LHS: spectrum vs k
   RHS: quantity vs t
   current time is changed via a slider

   :param ts: time array
   :param ks: ks array for each time
   :param spectra: dict label->array
   :param quantities: dict label->quantity


.. py:function:: interactive_3D_logplot_by_z(X: pyloggrid.Libs.singlethread_numpy.np.ndarray, Y: pyloggrid.Libs.singlethread_numpy.np.ndarray, V: pyloggrid.Libs.singlethread_numpy.np.ndarray, Z: pyloggrid.Libs.singlethread_numpy.np.ndarray = None) -> tuple[matplotlib.widgets.Slider, Any, Any]

   An interactive 3D logplot, sliced by ``Z`` if given.

   .. warning:: As for all interactive functions, the returned val must be assigned, ex via ``_ = my_interactive_function(...)``

   You can either provide 3D arrays (X, Y, V, Z[:,:,0]) or 2D arrays (X, Y, V).

   :param X:
   :param Y:
   :param V: values
   :param Z: optional 1D Z axis


.. py:function:: interactive_grid_imshow(grid: pyloggrid.LogGrid.Grid.Grid, update_data: Callable[[Any, float], pyloggrid.Libs.singlethread_numpy.np.ndarray], slider_params: tuple[float | None, float | None, float | None, str | None, str | None] = (0, 1, None, '', None)) -> tuple[matplotlib.widgets.Slider, Any]

   Imshow with slider, with axes formatted by the grid.

   .. warning:: As for all interactive functions, the returned val must be assigned, ex via ``_ = my_interactive_function(...)``

   :param grid:
   :param update_data: a function that takes the plotting ax and the slider's value, and returns an array to plot of size (N, N)
   :param slider_params: (vmin, vmax, vstep, title, vformat), all optional


.. py:function:: interactive_grid_3Dslice(grid: pyloggrid.LogGrid.Grid.Grid, update_data: Callable[[Any, float], pyloggrid.Libs.singlethread_numpy.np.ndarray], slider_params: tuple[float | None, float | None, float | None, str | None, str | None] = (0, 1, None, '', None)) -> tuple[matplotlib.widgets.Slider, Any]

   Interactive 3D slice of a grid field.

   .. warning:: As for all interactive functions, the returned val must be assigned, ex via ``_ = my_interactive_function(...)``

   :param grid:
   :param update_data: a function that takes the plotting ax and the slider's value, and returns a 3D array to plot
   :param slider_params: (vmin, vmax, vstep, title, vformat), all optional


.. py:function:: interactive_3D_logplot_positive(update_data: Callable[[Any, float], pyloggrid.Libs.singlethread_numpy.np.ndarray], slider_params: tuple[float | None, float | None, float | None, str | None, str | None] = (0, 1, None, '', None), threshold_fact: float = 5) -> tuple[matplotlib.widgets.Slider, Any]

   3D logplot of scalar field on kx,ky,kz>0.

   .. warning:: As for all interactive functions, the returned val must be assigned, ex via ``_ = my_interactive_function(...)``

   :param update_data: a function that takes the plotting ax and the slider's value, and returns a 3D array to plot
   :param slider_params: (vmin, vmax, vstep, title, vformat), all optional
   :param threshold_fact: which points to hide, relative to max(data)


.. py:function:: rand_cmap(nlabels: int, type_: Literal[bright, soft] = 'bright', first_color_black: bool = True, last_color_black: bool = False) -> matplotlib.colors.LinearSegmentedColormap

   Creates a random colormap to be used together with matplotlib. Useful for segmentation tasks

   :param nlabels: Number of labels (size of colormap)
   :param type_: 'bright' for strong colors, 'soft' for pastel colors
   :param first_color_black: Option to use first color as black
   :param last_color_black: Option to use last color as black

   :returns: colormap for matplotlib