netsse.tools.viz.plot_dirwavespec
=================================

.. py:function:: netsse.tools.viz.plot_dirwavespec(spec, dirs, freqs, unit_dirs='deg', unit_freqs='Hz', levels=None, cmap='turbo', vmin=None, vmax=None, freq_max=None, show_dirlabels=True, show_freqlabels=True, ax=None)

   Plots the input directional wave spectrum in a polar diagram.

   The plot shows the power spectral density (PSD) distribution over wave frequencies and
   directions.

   :param spec: Directional wave spectrum to be plotted. This must be a 2-D array of shape either
                `(Ndirs,Nfreqs)` or `(Nfreqs,Ndirs)`.
   :type spec: array_like
   :param dirs: Directions of the spectrum.
   :type dirs: array_like of shape (`Ndirs`,)
   :param freqs: Frequencies of the spectrum.
   :type freqs: array_like of shape (`Nfreqs`,)
   :param unit_dirs: Unit of the directions, either ``'deg'`` for degrees or ``'rad'`` for radians.
                     Default is ``'deg'``.
   :type unit_dirs: {'deg','rad'}, optional
   :param unit_freqs: Unit of the frequencies, either ``'Hz'`` for Hertz or ``'rad/s'`` for radians per second.
                      Default is ``'Hz'``.
   :type unit_freqs: {'Hz','rad/s'}, optional
   :param levels: Contour levels to use for the plot. If ``None``, levels are automatically determined
                  according to the formula below:

                  :math:`vmin*(vmax/vmin)^{i/29}` for :math:`i=0,1,...,29`.
                  Default is ``None``.
   :type levels: array_like, optional
   :param cmap: Colormap to use for the plot. Default is ``'turbo'``.

                .. note::
                    Other colormap options include ``'viridis'``, ``'plasma'``, ``'inferno'``, ``'magma'``.
                    Visit the `Matplotlib documentation
                    <https://matplotlib.org/stable/tutorials/colors/colormaps.html>`_ for an overview of
                    the options.
   :type cmap: str, optional
   :param vmin: Minimum value for the colormap. Default is ``None``, which means to use the value
                :math:`10^{-1/2}`.
   :type vmin: float, optional
   :param vmax: Maximum value for the colormap. Default is ``None``, which means to use the maximum value
                in ``spec``.

                .. warning::
                    ``vmin`` and ``vmax`` are used to set the colormap limits. These options will override the lower and upper limits of ``levels``, if the latter option is used.
   :type vmax: float, optional
   :param freq_max: Maximum frequency to plot. Default is ``None``, which means to use the maximum frequency in
                    the input data.
   :type freq_max: float, optional
   :param show_dirlabels: Whether to show direction labels.
                          If ``True``, shows labels in degrees. If ``'compass'``, shows compass directions.
                          If ``False``, no labels are shown. Default is ``True``.
   :type show_dirlabels: {True,False,'compass'}, optional
   :param show_freqlabels: Whether to show frequency labels. If ``True``, shows only the maximum frequency label.
                           If ``'all'``, shows all labels. If ``False``, no labels are shown. Default is ``True``.
   :type show_freqlabels: {True,False,'all'}, optional
   :param ax: Axes object to plot on. If ``None``, a new figure and axes are created. Default is ``None``.
   :type ax: matplotlib.axes, optional

   :returns: **ax** -- The axes object with the plot.
   :rtype: matplotlib.axes._subplots.PolarAxesSubplot

   .. rubric:: Example

   >>> # Generate some example data
   >>> freqs = np.linspace(0.05, 0.5, 50)
   >>> dirs = np.linspace(0, 360, 36)
   >>> spec = np.random.rand(36, 50)
   >>> # Plot the directional wave spectrum
   >>> plot_dirwavespec(spec, dirs, freqs)