*****************************
:py:mod:`wildboar.utils.plot`
*****************************

.. py:module:: wildboar.utils.plot

.. autoapi-nested-parse::

   Plotting utilities.

   ..
       !! processed by numpydoc !!


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

Classes
-------

.. autoapisummary::

   wildboar.utils.plot.MidpointNormalize



Functions
---------

.. autoapisummary::

   wildboar.utils.plot.plot_frequency_domain
   wildboar.utils.plot.plot_time_domain



.. py:class:: MidpointNormalize(vmin=None, vmax=None, midpoint=None)



   
   Normalise values with a specified midpoint.


   :Parameters:

       **vmin** : float, optional
           The minumum value.

       **vmax** : float, optional
           The maximum value.

       **midpoint** : float, optional
           The midpoint of the values.














   ..
       !! processed by numpydoc !!

   .. py:method:: autoscale(A)

      
      Set *vmin*, *vmax* to min, max of *A*.
















      ..
          !! processed by numpydoc !!


   .. py:method:: autoscale_None(A)

      
      If *vmin* or *vmax* are not set, use the min/max of *A* to set them.
















      ..
          !! processed by numpydoc !!


   .. py:method:: inverse(value)

      
      Maps the normalized value (i.e., index in the colormap) back to image
      data value.


      :Parameters:

          **value**
              Normalized value.














      ..
          !! processed by numpydoc !!


   .. py:method:: process_value(value)
      :staticmethod:


      
      Homogenize the input *value* for easy and efficient normalization.

      *value* can be a scalar or sequence.

      :Parameters:

          **value**
              Data to normalize.

      :Returns:

          **result** : masked array
              Masked array with the same shape as *value*.

          **is_scalar** : bool
              Whether *value* is a scalar.








      .. rubric:: Notes

      Float dtypes are preserved; integer types with two bytes or smaller are
      converted to np.float32, and larger types are converted to np.float64.
      Preserving float32 when possible, and using in-place operations,
      greatly improves speed for large arrays.





      ..
          !! processed by numpydoc !!


   .. py:method:: scaled()

      
      Return whether *vmin* and *vmax* are both set.
















      ..
          !! processed by numpydoc !!


.. py:function:: plot_frequency_domain(x, y=None, *, ax=None, n_samples=100, jitter=False, sample_spacing=1, frequency=False, cmap='Dark2')

   
   Plot the samples in the freqency domain.


   :Parameters:

       **x** : array-like of shape (n_sample, n_timestep)
           The samples.

       **y** : array-like of shape (n_samples, ), optional
           The labels.

       **ax** : Axes, optional
           The matplotlib Axes-object.

       **n_samples** : int, optional
           The maximum number of samples to plot. If n_samples is larger than the number
           of samples in x or None, all samples are plotted.

       **jitter** : bool, optional
           Add jitter to the amplitude lines.

       **sample_spacing** : int, optional
           The frequency domain sample spacing.

       **frequency** : bool, optional
           Show the frequency bins.

       **cmap** : str, optional
           The colormap.

   :Returns:

       Axes
           The axes object that has been plotted.










   .. rubric:: Examples

   >>> from wildboar.utils.plot import plot_frequency_domain
   >>> from wildboar.datasets import load_gun_point
   >>> X, y = load_gun_point(X, y)
   >>> plot_frequency_domain(X, y, n_sample=10)



   ..
       !! processed by numpydoc !!

.. py:function:: plot_time_domain(x, y=None, *, n_samples=100, ax=None, alpha=0.5, linewidth=0.5, zorder=-1, cmap='Dark2', show_legend=8)

   
   Plot the samples in the time domain.


   :Parameters:

       **x** : array-like of shape (n_sample, n_timestep)
           The samples.

       **y** : array-like of shape (n_samples, ), optional
           The labels, assumed to be discrete labels.

       **n_samples** : int, optional
           The maximum number of samples to plot. If n_samples is larger than the number
           of samples in x or None, all samples are plotted.

       **ax** : Axes, optional
           The matplotlib Axes-object.

       **alpha** : float, optional
           The opacity of the samples.

       **linewidth** : float, optional
           The width of the sample lines.

       **zorder** : int, optional
           The order where the samples are plotted. By default we plot the samples
           at -1.

       **cmap** : str, optional
           The colormap used to colorize samples according to its label.

       **show_legend** : bool or int, optional
           Whether the legend of labels are show.
           
           - if bool, show the legend if y is not None
           - if int, show the legend if the number of labels are lower than the
             show_legend parameter value

   :Returns:

       Axes
           The axes object that has been plotted.










   .. rubric:: Examples

   >>> from wildboar.utils.plot import plot_time_domain
   >>> from wildboar.datasets import load_gun_point
   >>> X, y = load_gun_point(X, y)
   >>> plot_time_domain(X, y, n_sample=10)



   ..
       !! processed by numpydoc !!