gerg_plotting
=============

.. py:module:: gerg_plotting

.. autoapi-nested-parse::

   A module for standardized plotting at GERG



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/gerg_plotting/data_classes/index
   /autoapi/gerg_plotting/modules/index
   /autoapi/gerg_plotting/plotting_classes/index
   /autoapi/gerg_plotting/tools/index






Package Contents
----------------

.. py:class:: Animator

   A class for creating animations (GIFs) from a sequence of images generated by a plotting function.

   This class handles both in-memory and disk-based frame generation depending on the number
   of frames, optimizing memory usage for larger animations.

   Parameters
   ----------
   image_dpi : int, optional
       Resolution (dots per inch) for saved images, default is 300

   Attributes
   ----------
   plotting_function : Callable
       Function used to generate each frame
   param_list : list[dict]
       List of parameter dictionaries for each frame
   num_iterations : int
       Total number of frames to generate
   duration : int | float
       Duration of each frame in milliseconds
   frames : list
       List to store generated frames in memory
   gif_filename : Path
       Output path for the generated GIF
   images_path : Path
       Directory for temporary image storage
   image_files : list
       List of generated image file paths
   function_kwargs : dict
       Additional arguments for the plotting function


   .. py:method:: animate(plotting_function, param_dict, gif_filename: str, fps=24, **kwargs) -> None

      Create and save a GIF animation.

      Parameters
      ----------
      plotting_function : Callable
          Function that generates each frame
      param_dict : dict
          Dictionary of parameters for frame generation
      gif_filename : str
          Output path for the GIF
      fps : int, optional
          Frames per second, default is 24
      ``**kwargs``
          Additional arguments passed to plotting_function



   .. py:attribute:: duration
      :type:  int | float


   .. py:attribute:: frames
      :type:  list


   .. py:attribute:: function_kwargs
      :type:  dict


   .. py:attribute:: gif_filename
      :type:  pathlib.Path


   .. py:attribute:: image_dpi
      :type:  int


   .. py:attribute:: image_files
      :type:  list


   .. py:attribute:: images_path
      :type:  pathlib.Path


   .. py:attribute:: iteration_param
      :type:  str


   .. py:attribute:: num_iterations
      :type:  int


   .. py:attribute:: param_list
      :type:  list[dict]


   .. py:attribute:: plotting_function
      :type:  Callable


.. py:class:: Bathy

   Bathy class for handling bathymetry data and visualization.

   Attributes
   ----------
   lat : Iterable | Variable | None
       Latitude values or Variable object containing latitude data
   lon : Iterable | Variable | None
       Longitude values or Variable object containing longitude data
   depth : Iterable | Variable | None
       Depth values or Variable object containing depth data
   time : Iterable | Variable | None
       Time values or Variable object containing temporal data
   bounds : Bounds
       Object containing spatial and vertical boundaries for the dataset.
   resolution_level : float or int, optional
       Degree resolution for coarsening the dataset, default is 5.
   contour_levels : int, optional
       Number of contour levels for visualization, default is 50.
   land_color : list
       RGBA color values for representing land, default is [231/255, 194/255, 139/255, 1].
   vmin : float or int, optional
       Minimum value for the colormap, default is 0.
   cmap : Colormap
       Colormap for bathymetry visualization, default is 'Blues'.
   cbar_show : bool
       Whether to display a colorbar, default is True.
   cbar : matplotlib.colorbar.Colorbar
       Colorbar for the bathymetry visualization.
   cbar_nbins : int
       Number of bins for colorbar ticks, default is 5.
   cbar_kwargs : dict
       Additional keyword arguments for the colorbar.
   center_of_mass : tuple
       Center of mass of the bathymetry data (longitude, latitude, depth).
   label : str
       Label for the bathymetry data, default is 'Bathymetry'.


   .. py:method:: add_colorbar(fig: matplotlib.figure.Figure, divider, mappable: matplotlib.axes.Axes, nrows: int) -> None

      Add a colorbar to the figure.

      Parameters
      ----------
      fig : matplotlib.figure.Figure
          The figure to which the colorbar is added.
      divider : AxesDivider
          Divider to place the colorbar appropriately.
      mappable : matplotlib.axes.Axes
          The mappable object (e.g., image or contour plot).
      nrows : int
          Number of rows in the figure layout.

      Returns
      -------
      matplotlib.colorbar.Colorbar
          The created colorbar instance.



   .. py:method:: adjust_cmap() -> None

      Adjust the colormap by cropping and adding land color.



   .. py:attribute:: bounds
      :type:  gerg_plotting.data_classes.bounds.Bounds


   .. py:attribute:: cbar
      :type:  matplotlib.colorbar.Colorbar


   .. py:attribute:: cbar_kwargs
      :type:  dict


   .. py:attribute:: cbar_nbins
      :type:  int


   .. py:attribute:: cbar_show
      :type:  bool


   .. py:property:: center_of_mass

      Property to compute and return center of mass.



   .. py:property:: cmap

      Property to return adjusted colormap.



   .. py:attribute:: contour_levels
      :type:  int


   .. py:method:: copy()

      Creates a deep copy of the instrument object.



   .. py:property:: depth

      Property to handle scaled depth values.



   .. py:method:: get_bathy() -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

      Load and process bathymetry data.

      Returns
      -------
      tuple of np.ndarray
          Longitude, latitude, and depth values.

      Raises
      ------
      ValueError
          If the bounds attribute is not provided.



   .. py:method:: get_vars() -> list

      Gets a list of all available variables.



   .. py:property:: label

      Property to handle label with units.



   .. py:attribute:: land_color
      :type:  list


   .. py:property:: lat

      Property to handle latitude values.



   .. py:property:: lon

      Property to handle longitude values.



   .. py:attribute:: resolution_level
      :type:  float | int | None


   .. py:attribute:: vmin
      :type:  int | float


.. py:class:: Bounds

   Represents geographic and depth bounds for a spatial dataset.

   Attributes
   ----------
   lat_min : float | int | None
       Minimum latitude of the bounds. Must be smaller than `lat_max`.
   lat_max : float | int | None
       Maximum latitude of the bounds.
   lon_min : float | int | None
       Minimum longitude of the bounds. Must be smaller than `lon_max`.
   lon_max : float | int | None
       Maximum longitude of the bounds.
   depth_bottom : float | int | None
       Maximum depth value (positive, in meters). Represents the bottom of the range.
   depth_top : float | int | None
       Minimum depth value (positive, in meters). Represents the top of the range (e.g., surface).
   vertical_scalar : float | int | None
       A scaling factor applied to depth values. Default is 1.
   vertical_units : str | None
       Units for the vertical depth values. Default is "m".


   .. py:attribute:: depth_bottom
      :type:  float | int | None


   .. py:attribute:: depth_top
      :type:  float | int | None


   .. py:attribute:: lat_max
      :type:  float | int | None


   .. py:attribute:: lat_min
      :type:  float | int | None


   .. py:attribute:: lon_max
      :type:  float | int | None


   .. py:attribute:: lon_min
      :type:  float | int | None


   .. py:attribute:: vertical_scalar
      :type:  float | int | None


   .. py:attribute:: vertical_units
      :type:  str | None


.. py:class:: CoveragePlot

   Bases: :py:obj:`Base`


   A class for creating and managing plots showing multiple coverage areas.

   Parameters
   ----------
   fig : Figure, optional
       Matplotlib figure object.
   ax : Axes, optional
       Matplotlib axes object.
   figsize : tuple, optional
       Size of the figure (width, height).
   horizontal_padding : float
       Padding on left and right of plot. Default is 0.25.
   vertical_padding : float
       Padding on top and bottom of plot. Default is 0.75.
   xlabels : list
       Labels for x-axis ticks.
   ylabels : list
       Labels for y-axis ticks.
   cmap : str or Colormap
       Colormap for coverage areas.
   coverage_color_default : str or tuple
       Default color for coverages if specified.

   Attributes
   ----------
   color_iterator : itertools.cycle
       Iterator for cycling through colors.
   coverages : list
       List of Coverage objects.
   grid : Grid
       Grid object for the plot.
   plotting_kwargs : dict
       Default keyword arguments for plotting.


   .. py:method:: add_coverage(xrange, yrange, label=None, **kwargs)

      Add a new coverage area to the plot.

      Parameters
      ----------
      xrange : list or scalar
          Range or single value for x-axis coverage.
      yrange : list or scalar
          Range or single value for y-axis coverage.
      label : str, optional
          Label for the coverage area.
      ``**kwargs``
          Additional keyword arguments for coverage customization.

      Raises
      ------
      ValueError
          If xrange and yrange are not the same length.



   .. py:method:: add_grid(show_grid: bool)

      Add grid to the plot if requested.

      Parameters
      ----------
      show_grid : bool
          Whether to show the grid.



   .. py:attribute:: ax
      :type:  matplotlib.axes.Axes


   .. py:attribute:: cmap
      :type:  str | matplotlib.colors.Colormap


   .. py:attribute:: color_iterator
      :type:  itertools.cycle


   .. py:method:: coverage_color()

      Get the next color for a coverage area.

      Returns
      -------
      tuple or str
          RGBA color tuple or specified default color.



   .. py:attribute:: coverage_color_default


   .. py:attribute:: coverages
      :type:  list[Coverage]


   .. py:method:: custom_ticks(labels, axis: str)

      Set custom tick labels for specified axis.

      Parameters
      ----------
      labels : list
          List of tick labels.
      axis : str
          Axis to customize ('x' or 'y').



   .. py:attribute:: fig
      :type:  matplotlib.figure.Figure


   .. py:attribute:: figsize
      :type:  tuple


   .. py:attribute:: grid
      :type:  Grid


   .. py:method:: handle_ranges(xrange, yrange)

      Convert string labels to numeric indices for plotting.

      Parameters
      ----------
      xrange : list
          Range values for x-axis.
      yrange : list
          Range values for y-axis.

      Returns
      -------
      tuple
          Processed (xrange, yrange) with numeric values.



   .. py:attribute:: horizontal_padding
      :type:  float


   .. py:method:: init_figure() -> None

      Initialize figure and axes if not provided.



   .. py:method:: plot(show_grid=True)

      Create the complete coverage plot.

      Parameters
      ----------
      show_grid : bool, optional
          Whether to show grid lines. Default is True.



   .. py:method:: plot_coverages()

      Plot all coverage areas on the figure.



   .. py:attribute:: plotting_kwargs
      :type:  dict


   .. py:method:: save(filename, **kwargs)

      Save the current figure to a file.

      Parameters
      ----------
      filename : str
          Path to save the figure.
      ``**kwargs``
          Additional keyword arguments passed to savefig.

      Raises
      ------
      ValueError
          If no figure exists to save.



   .. py:method:: set_padding()

      Set plot limits with padding.



   .. py:method:: set_up_plot(show_grid: bool = True)

      Configure the plot with all necessary components.

      Parameters
      ----------
      show_grid : bool, optional
          Whether to show grid lines. Default is True.



   .. py:method:: show(**kwargs)

      Display the plot.

      Parameters
      ----------
      ``**kwargs``
          Additional keyword arguments passed to plt.show().



   .. py:attribute:: vertical_padding
      :type:  float


   .. py:attribute:: xlabels
      :type:  list


   .. py:attribute:: ylabels
      :type:  list


.. py:class:: Data

   Represents a spatial dataset with various oceanographic or atmospheric variables.

   Attributes
   ----------
   lat : Iterable | Variable | None
       Latitude values or Variable object containing latitude data
   lon : Iterable | Variable | None
       Longitude values or Variable object containing longitude data
   depth : Iterable | Variable | None
       Depth values or Variable object containing depth data
   time : Iterable | Variable | None
       Time values or Variable object containing temporal data
   bounds : Bounds, optional
       Geographic and depth bounds for the dataset
   custom_variables : dict
       Dictionary to store additional custom variables
   temperature : Iterable, Variable, or None, optional
       Temperature data, in °C, with optional colormap and range specifications.
   salinity : Iterable, Variable, or None, optional
       Salinity data with optional colormap and range specifications.
   density : Iterable, Variable, or None, optional
       Density data, in kg/m³, with optional colormap and range specifications.
   u : Iterable, Variable, or None, optional
       Zonal velocity (u-component) in m/s, with optional colormap and range specifications.
   v : Iterable, Variable, or None, optional
       Meridional velocity (v-component) in m/s, with optional colormap and range specifications.
   w : Iterable, Variable, or None, optional
       Vertical velocity (w-component) in m/s, with optional colormap and range specifications.
   speed : Iterable, Variable, or None, optional
       Speed data, derived or directly assigned, in m/s, with optional colormap and range specifications.
   chlor : Iterable, Variable, or None, optional
       Chlorophyll data, in μg/L, with optional colormap and range specifications.
   cdom : Iterable, Variable, or None, optional
       CDOM data, in ppb, with optional colormap and range specifications.
   turbidity : Iterable, Variable, or None, optional
       Turbidity data, dimensionless, with optional colormap and range specifications.
   bounds : Bounds
       Spatial bounds of the data.


   .. py:method:: add_custom_variable(variable: gerg_plotting.data_classes.variable.Variable, exist_ok: bool = False) -> None

      Add a custom Variable object accessible via both dot and dict syntax.

      Parameters
      ----------
      variable : Variable
          The Variable object to add
      exist_ok : bool, optional
          If True, replace existing variable if it exists, by default False

      Raises
      ------
      TypeError
          If provided object is not a Variable instance
      AttributeError
          If variable name already exists and exist_ok is False



   .. py:property:: bounds
      :type: gerg_plotting.data_classes.bounds.Bounds


      Get or set the bounds of the data.



   .. py:attribute:: bounds_padding


   .. py:attribute:: buoyancy_frequency
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:method:: calcluate_PSD(sampling_freq, segment_length, theta_rad=None) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray] | tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

      Calculate the power spectral density (PSD) using Welch's method.

      Parameters
      ----------
      sampling_freq : float
          Sampling frequency of the data in Hz.
      segment_length : int
          Length of each segment for Welch's method.
      theta_rad : float, optional
          Angle of rotation in radians. Rotates the u and v components if specified.

      Returns
      -------
      tuple
          A tuple containing the frequency array and PSD values for the velocity components.
          If the vertical component (w) is available, it is also included in the tuple.



   .. py:method:: calculate_speed(include_w: bool = False) -> None

      Calculate the speed from velocity components.

      Parameters
      ----------
      include_w : bool, optional
          If True, includes the vertical velocity (w-component) in the speed calculation.
          Defaults to False.



   .. py:attribute:: cdom
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: chlor
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:method:: copy()

      Creates a deep copy of the instrument object.



   .. py:attribute:: custom_variables
      :type:  dict


   .. py:method:: date2num() -> list

      Converts time values to numerical values.



   .. py:attribute:: density
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: depth
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:method:: detect_bounds(bounds_padding=0) -> gerg_plotting.data_classes.bounds.Bounds

      Detect the geographic bounds of the data, applying padding if specified.

      An intentional effect of this function:
          will only calculate the bounds when self.bounds is None,
          so that it does not overwrite the user's custom bounds,
          this will also ensure that the bounds is not repeatedly calculated unless desired,
          can recalculate self.bounds using a new bounds_padding value if self.bounds is set to None

      The depth bounds are not affected by the bounds padding, therfore the max and min values of the depth data are used

      Parameters
      ----------
      bounds_padding : float, optional
          Padding to add to the detected bounds, by default 0

      Returns
      -------
      Bounds
          Object containing the detected geographic and depth bounds




   .. py:method:: get_vars(have_values: bool | None = None) -> list

      Gets a list of all available variables.



   .. py:attribute:: lat
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: lon
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: oxygen
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:method:: remove_custom_variable(variable_name) -> None

      Remove a custom variable from the instrument.

      Parameters
      ----------
      variable_name : str
          Name of the variable to remove



   .. py:attribute:: salinity
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: speed
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: temperature
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: time
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: turbidity
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: u
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: v
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


   .. py:attribute:: w
      :type:  Iterable | gerg_plotting.data_classes.variable.Variable | None


.. py:class:: Histogram

   Bases: :py:obj:`gerg_plotting.plotting_classes.plotter.Plotter`


   A class for plotting histograms from instrument data using matplotlib.

   This class provides methods for creating 1D, 2D, and 3D histograms from data.
   Inherits from Plotter class for basic plotting functionality.


   .. py:method:: plot(var: str, fig=None, ax=None, **kwargs) -> None

      Plot a 1D histogram of the given variable.

      Parameters
      ----------
      var : str
          Name of the variable to plot
      fig : matplotlib.figure.Figure, optional
          Figure object to use for plotting
      ax : matplotlib.axes.Axes, optional
          Axes object to use for plotting
      ``**kwargs`` : dict
          Additional keyword arguments passed to matplotlib.pyplot.hist



   .. py:method:: plot2d(x: str, y: str, fig=None, ax=None, **kwargs) -> None

      Plot a 2D histogram for the x and y variables.

      Parameters
      ----------
      x : str
          Name of the x-axis variable
      y : str
          Name of the y-axis variable
      fig : matplotlib.figure.Figure, optional
          Figure object to use for plotting
      ax : matplotlib.axes.Axes, optional
          Axes object to use for plotting
      ``**kwargs`` : dict
          Additional keyword arguments passed to matplotlib.pyplot.hist2d



   .. py:method:: plot3d(x: str, y: str, fig=None, ax=None, **kwargs) -> None

      Plot a 3D surface plot based on a 2D histogram.

      Parameters
      ----------
      x : str
          Name of the x-axis variable
      y : str
          Name of the y-axis variable
      fig : matplotlib.figure.Figure, optional
          Figure object to use for plotting
      ax : matplotlib.axes.Axes, optional
          Axes object to use for plotting
      ``**kwargs`` : dict
          Additional keyword arguments passed to numpy.histogram2d



.. py:class:: MapPlot

   Bases: :py:obj:`gerg_plotting.plotting_classes.plotter.Plotter`


   A class for plotting geographic data on maps using Cartopy and Matplotlib.

   Parameters
   ----------
   bathy : Bathy, optional
       Bathymetric data object
   grid_spacing : int, optional
       Spacing between gridlines in degrees, default is 1

   Attributes
   ----------
   sc : matplotlib.collections.PathCollection
       Scatter plot collection
   gl : cartopy.mpl.gridliner.Gridliner
       Gridliner for map coordinates
   cbar_var : matplotlib.colorbar.Colorbar
       Colorbar for plotted variable
   cbar_bathy : matplotlib.colorbar.Colorbar
       Colorbar for bathymetry


   .. py:attribute:: bathy
      :type:  gerg_plotting.data_classes.bathy.Bathy


   .. py:property:: bathy_initialized

      Check if bathymetry is properly initialized



   .. py:attribute:: cbar_bathy
      :type:  matplotlib.colorbar.Colorbar


   .. py:attribute:: cbar_var
      :type:  matplotlib.colorbar.Colorbar


   .. py:property:: coordinate_labels

      Configure coordinate label formatting



   .. py:method:: get_color_settings(var: str | None) -> tuple[str | numpy.ndarray, matplotlib.colors.Colormap]

      Get color and colormap settings for specified variable.

      Parameters
      ----------
      var : str or None
          Variable name for color mapping
          
      Returns
      -------
      tuple
          (color, cmap) where color is str or ndarray and cmap is Colormap



   .. py:attribute:: gl
      :type:  cartopy.mpl.gridliner.Gridliner


   .. py:attribute:: grid_spacing
      :type:  int


   .. py:property:: gridlines

      Configure and return gridlines based on current settings



   .. py:property:: map_extent

      Get map extent from data bounds



   .. py:method:: quiver(x: str = 'lon', y: str = 'lat', quiver_density: int = None, quiver_scale: float = None, grid: bool = True, show_bathy: bool = True, show_coastlines: bool = True, fig=None, ax=None) -> None

      Create quiver plot for vector data.

      Parameters
      ----------
      x : str, optional
          X-axis variable name, default 'lon'
      y : str, optional
          Y-axis variable name, default 'lat'
      quiver_density : int, optional
          Density of quiver arrows
      quiver_scale : float, optional
          Scaling factor for arrow length
      grid : bool, optional
          Whether to show grid, default True
      show_bathy : bool, optional
          Whether to show bathymetry, default True
      show_coastlines : bool, optional
          Whether to show coastlines, default True
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on



   .. py:property:: quiver_step

      Step size for quiver plot density based on data length



   .. py:attribute:: sc
      :type:  matplotlib.collections.PathCollection


   .. py:method:: scatter(var: str | None = None, show_bathy: bool = True, show_coastlines: bool = True, pointsize=3, linewidths=0, grid=True, show_coords=True, fig=None, ax=None) -> None

      Create scatter plot of points on map.

      Parameters
      ----------
      var : str or None, optional
          Variable name for color mapping
      show_bathy : bool, optional
          Whether to show bathymetry, default True
      show_coastlines : bool, optional
          Whether to show coastlines, default True
      pointsize : int, optional
          Size of scatter points, default 3
      linewidths : int, optional
          Width of point edges, default 0
      grid : bool, optional
          Whether to show grid, default True
      show_coords : bool, optional
          Whether to show coordinates, default True
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on



.. py:class:: ScatterPlot

   Bases: :py:obj:`gerg_plotting.plotting_classes.plotter.Plotter`


   Class for creating scatter plots from Data objects.

   Inherits from Plotter class for basic plotting functionality. Provides methods
   for various scatter plot types including T-S diagrams, hovmoller plots, and
   velocity vector plots.


   .. py:method:: TS(color_var=None, fig=None, ax=None, contours: bool = True, scatter_kwargs=None, contour_kwargs=None) -> None

      Create temperature-salinity diagram.

      Parameters
      ----------
      color_var : str or None, optional
          Variable name for color mapping
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on
      contours : bool, optional
          Whether to show sigma-theta contours, default True
      scatter_kwargs : dict, optional
          Additional arguments to pass to scatter plot (see matplotlib.pyplot.scatter)
      contour_kwargs : dict, optional
          Additional arguments to pass to contour plot (see matplotlib.pyplot.contour)



   .. py:method:: calculate_quiver_step(num_points, quiver_density) -> int

      Calculate step size for quiver plot density.

      Parameters
      ----------
      num_points : int
          Total number of data points
      quiver_density : int
          Desired density of quiver arrows

      Returns
      -------
      int
          Step size for data sampling



   .. py:method:: cross_section(longitude, latitude) -> None
      :abstractmethod:


      Method placeholder for plotting cross-sections.

      Args:
          longitude: Longitude line for the cross-section.
          latitude: Latitude line for the cross-section.

      Raises:
          NotImplementedError: Indicates that the method is not yet implemented.



   .. py:method:: get_density_color_data(color_var: str) -> numpy.ndarray

      Get color data for density plotting.

      Parameters
      ----------
      color_var : str
          Variable name for color data

      Returns
      -------
      np.ndarray
          Array of color values



   .. py:method:: hovmoller(var: str, fig=None, ax=None, **scattter_kwargs) -> None

      Create depth vs time plot colored by variable.

      Parameters
      ----------
      var : str
          Variable name for color mapping
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on
      ``**scattter_kwargs``
          Additional arguments for scatter plot (see matplotlib.pyplot.scatter)



   .. py:method:: power_spectra_density(psd_freq=None, psd=None, var_name: str = None, sampling_freq=None, segment_length=None, theta_rad=None, highlight_freqs: list = None, fig=None, ax=None) -> None

      Create power spectral density plot.

      Parameters
      ----------
      psd_freq : array-like, optional
          Frequency values
      psd : array-like, optional
          Power spectral density values
      var_name : str, optional
          Variable name for PSD calculation
      sampling_freq : float, optional
          Sampling frequency
      segment_length : int, optional
          Length of segments for PSD calculation
      theta_rad : float, optional
          Angle in radians
      highlight_freqs : list, optional
          Frequencies to highlight
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on

      Raises
      ------
      ValueError
          If neither PSD values nor calculation parameters are provided



   .. py:method:: quiver1d(x: str, quiver_density: int = None, quiver_scale: float = None, fig=None, ax=None) -> None

      Create 1D quiver plot for velocity data.

      Parameters
      ----------
      x : str
          Variable name for x-axis
      quiver_density : int, optional
          Density of quiver arrows
      quiver_scale : float, optional
          Scaling factor for arrow length
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on



   .. py:method:: quiver2d(x: str, y: str, quiver_density: int = None, quiver_scale: float = None, fig=None, ax=None) -> None

      Create 2D quiver plot for velocity data.

      Parameters
      ----------
      x : str
          Variable name for x-axis
      y : str
          Variable name for y-axis
      quiver_density : int, optional
          Density of quiver arrows
      quiver_scale : float, optional
          Scaling factor for arrow length
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on



   .. py:method:: scatter(x: str, y: str, color_var: str | None = None, invert_yaxis: bool = False, fig=None, ax=None, **scattter_kwargs) -> None

      Create scatter plot of two variables with optional color mapping.

      Parameters
      ----------
      x : str
          Variable name for x-axis
      y : str
          Variable name for y-axis
      color_var : str or None, optional
          Variable name for color mapping
      invert_yaxis : bool, optional
          Whether to invert y-axis
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on
      ``**scattter_kwargs``
          Additional arguments for scatter plot (see matplotlib.pyplot.scatter)

      Returns
      -------
      matplotlib.collections.PathCollection
          Scatter plot object



   .. py:method:: scatter3d(x: str, y: str, z: str, color_var: str | None = None, invert_yaxis: bool = False, fig=None, ax=None, **scattter_kwargs) -> None

      Create scatter plot of two variables with optional color mapping.

      Parameters
      ----------
      x : str
          Variable name for x-axis
      y : str
          Variable name for y-axis
      color_var : str or None, optional
          Variable name for color mapping
      invert_yaxis : bool, optional
          Whether to invert y-axis
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on
      ``**scattter_kwargs``
          Additional arguments for scatter plot (see matplotlib.pyplot.scatter)

      Returns
      -------
      matplotlib.collections.PathCollection
          Scatter plot object



   .. py:method:: tricontourf(x: str, y: str, z: str, fig=None, ax=None, levels=None)

      Create filled contour plot of irregular grid data.

      Parameters
      ----------
      x : str
          Variable name for x-axis
      y : str
          Variable name for y-axis
      z : str
          Variable name for contour values
      fig : matplotlib.figure.Figure, optional
          Figure to plot on
      ax : matplotlib.axes.Axes, optional
          Axes to plot on
      levels : int, optional
          Number of contour levels



.. py:class:: ScatterPlot3D

   Bases: :py:obj:`gerg_plotting.plotting_classes.plotter_3d.Plotter3D`


   .. py:method:: make_points_3d(x: str, y: str, z: str) -> numpy.ndarray

      A helper to make a 3D NumPy array of points (n_points by 3)



   .. py:method:: map(var: str | None = None, show_var_cbar: bool = True, show_bathy_cbar: bool = True, show_plot=False) -> None


   .. py:method:: scatter(x: str, y: str, z: str, var: str | None = None, show_var_cbar: bool = True, show_plot: bool = False) -> None


   .. py:property:: scatter_scalar_bar_defaults
      :type: dict


      Returns the default settings for the scatter plot.



.. py:class:: Variable

   A class representing a scientific variable with its values and visualization properties.

   This class handles values arrays along with their metadata and visualization settings,
   providing methods for values access and label generation.

   Parameters
   ----------
   values : np.ndarray
       The numerical values for the variable
   name : str
       Name identifier for the variable
   cmap : Colormap, optional
       Matplotlib colormap for visualization
   units : str, optional
       Units of measurement
   vmin : float, optional
       Minimum value for visualization scaling
   vmax : float, optional
       Maximum value for visualization scaling
   label : str, optional
       Custom label for plotting

   Attributes
   ----------
   values : np.ndarray
       Flat numpy array containing the variable values
   name : str
       Variable name identifier
   cmap : Colormap
       Colormap for visualization
   units : str
       Units of measurement
   vmin : float
       Minimum value for visualization
   vmax : float
       Maximum value for visualization
   label : str
       Display label for plots


   .. py:property:: attrs
      :type: list


      List of all attributes for the variable.



   .. py:attribute:: cmap
      :type:  matplotlib.colors.Colormap


   .. py:method:: get_attrs() -> list

      Get list of all attributes for the variable.

      Returns
      -------
      list
          List of attribute names



   .. py:property:: label
      :type: str


      Formatted label including variable name and units if available.



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: units
      :type:  str


   .. py:attribute:: values
      :type:  numpy.ndarray


   .. py:property:: vmax
      :type: float


      Maximum value for visualization. Using 98th percentile for numeric data.



   .. py:property:: vmin
      :type: float


      Minimum value for visualization, using 2nd percentile for numeric data.



.. py:function:: data_from_csv(filename: str, mapped_variables: dict | None = None, custom_vars: str | list[str] | None = None, **kwargs)

   Create Data object from CSV file.

   Parameters
   ----------
   filename : str
       Path to CSV file
   mapped_variables : dict, optional
       Custom variable mapping
   custom_vars : str | list[str], optional
       Additional variable name(s) to include from DataFrame
   ``**kwargs``
       Additional arguments for Data initialization

   Returns
   -------
   Data
       Initialized Data object


.. py:function:: data_from_df(df: pandas.DataFrame, mapped_variables: dict | None = None, custom_vars: str | list[str] | None = None, **kwargs)

   Create Data object from DataFrame with optional custom variables.

   Parameters
   ----------
   df : pandas.DataFrame
       Source DataFrame
   mapped_variables : dict, optional
       Custom variable mapping
   custom_vars : str | list[str], optional
       Additional variable name(s) to include from DataFrame
   ``**kwargs`` : dict
       Additional arguments for Data initialization

   Returns
   -------
   Data
       Initialized Data object


.. py:function:: data_from_ds(ds: xarray.Dataset, interp_glider: bool = False, mapped_variables: dict | None = None, custom_vars: str | list[str] | None = None, **kwargs)

   Create Data object from xarray Dataset with optional custom variables.

   Parameters
   ----------
   ds : xarray.Dataset
       Input dataset to convert
   interp_glider : bool, optional
       Whether to interpolate glider positions
   mapped_variables : dict, optional
       Dictionary mapping variable names to dataset variables
   custom_vars : str | list[str], optional
       Additional variable name(s) to include from Dataset
   ``**kwargs`` : dict
       Additional arguments for Data initialization

   Returns
   -------
   Data
       New Data object containing the dataset variables


.. py:function:: data_from_netcdf(filename: str, mapped_variables: dict | None = None, interp_glider: bool = False, custom_vars: str | list[str] | None = None, **kwargs)

   Create Data object from NetCDF file.

   Parameters
   ----------
   filename : str
       Path to NetCDF file
   mapped_variables : dict or None, optional
       Dictionary mapping variable names to dataset variables  
   interp_glider : bool, optional
       Whether to interpolate glider lat/lon positions
   custom_vars : str | list[str], optional
       Additional variable name(s) to include from Dataset
   ``**kwargs``
       Additional keyword arguments passed to Data constructor

   Returns
   -------
   Data
       New Data object containing the NetCDF variables


.. py:function:: interp_glider_lat_lon(ds: xarray.Dataset) -> xarray.Dataset

   Interpolate all glider data variables that use m_time as their dimension.

   Parameters
   ----------
   ds : xarray.Dataset
       Dataset containing glider data

   Returns
   -------
   xarray.Dataset
       Dataset with all m_time variables interpolated to time dimension