# `cso_plot` module

Plotting tools.

## Class hierchy

- Figure

  - ColorbarFigure

## Classes and methods

class cso_plot.Figure(figsize=None)

  Bases: `object`

  Base class for figures.

  Close()

    Destroy figure.

  Export(filename)

    Export figure.

  AddAxes(position=(0.02, 0.02, 0.96, 0.96), domain=None, bmp=None)

    Add ax to figure.

    Optional arguments:

    - `position=(left,bottom,width,height)` : Relative position of lower left corner and size; defaults values ensure maximum axis.

    - `domain` : (left,right,bottom,top)

    - `bmp={..}` : dict with settings for geographical projection:

      - `projection` : ‘cyl’=cylindrical,

      - `raster` : (meridian_distance,parallel_distance)

      - `coastlines` : default True

      - `countries` : True or False

      - `rivers` : True or False

  Rectangle(rect, **kwargs)

    Draw rectangle with corners specified by:

        rect=(west,east,south,north)

    Optional keyword arguments are passed to `matplotlib.pyplot.plot()` method.

  StackFill(x, yy, labels=None)

    Add filled hatches to ax.

    Arguments:

    - `x` : N array

    - `yy` : NxM array

  OneToOne(*args, **kwargs)

    Add 1-1 line, set ax lims to be square.

    Arguments are passed to `plot()` method that adds the line to the axis.

class cso_plot.ColorbarFigure(figsize=None, position=None, domain=None, title=None, facecolor=None, bmp=None, cmap={}, cbar={})

  Bases: `Figure`

  Base class for figure with colorbar.

  Optional arguments passed to `Figure` class initialization:

  - `figsize`

  Optional arguments to setup data axes:

  - `position=(left,bottom,width,height)` : position of axes; defaults is guesed

  - `domain=(xmin,xmax,ymin,ymax)` : axes limits passed to ‘Figure.Set_Domain’

  - `title` : axes title

  - `projection` : used to setup map projection

  Optional arguments that define colorbar:

  - `cmap` : defines colormap, passed to `Set_ColorMap()` method

  - `cbar` : defines colorbar, passed to `Set_ColorBar()` (`False` to skip)

  - `bmp` : defines geographical projection, passed to `AddAxes()` method

  Set_ColorMap(colors=None, color_under=None, color_over=None, color_bad=None, ncolor=None)

    Define color map with ncolor` values. The rgb values in the colormap are interpolated between the specified colors. The ‘under’ and ‘over’ colors for lower and higher values, and ‘bad’ for masked data. The colormap is stored as the ‘cmap’ field.

    Optional arguments:

    - `colors` : either:

      - list with color description: `['white','yellow','red']`

      - locally impelemented definitions:

        - ‘wbrb’ (white-blue-red-brown)

        - ‘brb’ (blue-red-brown)

        - ‘bwr’ (blue-white-red)

        - ‘pwb’ (purple-white-brown)

      - colormaps from `cmcrameri` module:

            'cmcrameri.cm.navia_r'

      - predefined colormaps : ‘jet’, …

    - `color_under` : color descriptions for underflow

    - `color_over` : color descriptions for overflow

    - `color_bad` : color for masked values in numpy.ma (masked array)

    - `ncolor` : (int) number of slots in color table

    Attributes set by this routine:

    - `cmap` : colormap instance

    See also:

    - `matplotlib.pyplot.colorbar`

  Set_ColorNorm(values, vmin=None, vmax=None, vbounds=None)

    Setup a color normalization to map data values to an index in [0,1] . If an array ‘vbounds’ is specified, it should contain an increasing range of values that define the boundaries of interfals which have the same number of slots in the color map. Otherwise, the values are mapped linear from values in the interval ‘[vmin,vmax]’ to the slots in the color map.linear to [0,1] ; if these are not provided, the range will be the min/max of the suplied values.

    This routine sets the attributes: `cnorm`, `vmin`, `vmax`

    Arguments:

    - `values` : data to be displayed; use for min/max

    Optional keywords:

    - `vmin`, `vmax` : data range

    See also:

    - :py:class.`matplotlib.colors.normalize`

  Set_ColorBar(ticks=None, ntick=None, label=None, tickprops=None, **kwargs)

    Set colorbar properties.

    Keyword arguments:

    - `ticks` : tick locations (explicitly set)

    - `ntick` : number of tickmarks (distributed within vrange)

    - `label` : text below colorbar

    - `tickprops` : properties for ticklabels, e.g. `fontsize=20` etc ; see `matplotlib.text.Text` class for all supported properties

    Keyword arguments passed directly to `matplotlib.pyplot.colorbar` class, for example:

    - `orientation` : default `'horizontal'`, also `'vertical'` possible

    - `extend` : add left or right arrows: `'neither' | 'both' | 'min' | 'max'`

    - `drawedges` : lines between colors in colorbar ? True or False

    - `format` : used for labels, e.g. `'%g'` for general number or `'%3.1f'`

  Add_ColorBar(p)

    Fill the colorbar for the mappable `p`.

    Uses settings stored by `Set_ColorBar()` method.

    Arguments:

    - `p` : mappable object, output of `pcolor()`, `scatter()`, …

  PColor(xx, yy, cc, vmin=None, vmax=None, vbounds=None, **kwargs)

    Add pseudo color plot. If no grid keywords are provided, the domain specified in the initilization might be used; if no domain was provided, the axes are simply the dimension indices.

    Arguments:

    - `xx`, `yy` : 2D corner fields, shapes (ny+1,nx+1)

    - `cc` : data values, shape (ny,nx)

    Optional color mapping:

    - `vmin`,``vmax`` : data range for coloring, min and max values by default, or the settings for Scatter if that was called before

    - `vbounds` : instead of linear mapping of values to color map, specify with this variable a list of boundary values, each interval will take the same number of slots in the color map; typically use this with explicit definition of the ticks in the colorbar:

          cbar=dict(ticks=vbounds)

    Other keywords are passed directly to `matplotlib.pyplot.pcolormesh` class.

    Return value: `matplotlib.pyplot.pcolormesh` object

  PColorRGG(rgg, values, vmin=None, vmax=None, vbounds=None, **kwargs)

    Add pseudocolor fieds for values defined on reduced gaussian grid.

    Arguments:

    - `rgg` : grid_rgg.ReducedGrid object

    - `values` : 1D list with values, length is `rgg.npoint`

    Optional color mapping (see PColor):

    - `vmin`,``vmax``

    - `vbounds`

    Other keywords are passed directly to `matplotlib.pyplot.pcolormesh` class

  Scatter(xx, yy, vmin=None, vmax=None, vbounds=None, **kwargs)

    Plot cloud of scattered symbols.

    Arguments:

    - `xx`, `yy` : location lists

    - `vmin`,``vmax`` : data range for coloring, min and max values by default, or the settings for PColor if that was called before

    - `vbounds` : value boundaries (alternative for vmin,vmax)

    Optional keywords passed to ‘pyplot.scatter’, for example:

    - `c` : (list of) data value(s), mapped to colors

    - `s` : (list of) symbol size(s)

    - `marker` : marker symbol

    - `linewidths` : edge widths

  Polygons(xx, yy, values, vmin=None, vmax=None, vbounds=None, **kwargs)

    Add colored polygons.

    Arguments:

    - `xx`, `yy` : location arrays (npoly,ncorner)

    - `values` : data values (npoly) mapped to colors

    Optional arguments:

    - `vmin`,``vmax``data range for coloring, min and max values by default,

        or the settings for PColor if that was called before

    - `vbounds` : value boundaries (alternative for vmin,vmax)

  PolygonsMesh(xx, yy, values, vmin=None, vmax=None, vbounds=None, **kwargs)

    Add colored polygons.

    Arguments:

    - `xx`, `yy` : 2D corner fields, shapes (ny+1,nx+1)

    Optional arguments:

    - `vmin`,``vmax``data range for coloring, min and max values by default,

        or the settings for PColor if that was called before

    - `vbounds` : value boundaries (alternative for vmin,vmax)

  Density(x, y, bins=10, normed=False, **kwargs)

    Add density plot (2D histogram).

    Arguments are passed to `matplotlib.pyplot.hist2d()` method :

    - `x`, `y` : values

    - `bins` : number, array, or list of 2 arrays

  PlotAxes(oneone=False)

    Add x and y axes lines if necessary. Add 1-1 line if flag is set.

cso_plot.GetColorMap(colors=None, color_under=None, color_over=None, color_bad=None, ncolor=256)

  Define color map with N values. The rgb values in the colormap are interpolated between the specified colors. The ‘under’ and ‘over’ colors for lower and higher values, and ‘bad’ for masked data. The colormap is stored as the ‘cmap’ field.

  Arguments:

  - `colors` : either:

    - list with color description: [‘white’,’yellow’,’red’]

    - ‘wbrb’ (white-blue-red-brown)

    - ‘brb’ (blue-red-brown)

    - ‘bwr’ (blue-white-red)

  - `color_under` : color descriptions for underflow

  - `color_over` : color descriptions for overflow

  - `color_bad` : color for masked values in numpy.ma (masked array)

  - `ncolor` : (int) number of slots in color table

  Return values:

  - `cmap` : colormap instance

cso_plot.mid2bounds(x)

  Return 1D arrays with boundary values.

cso_plot.mid2corners(xx)

  Return 2D fields with corner values.

cso_plot.GetGrid(shp, xx=None, yy=None, x=None, y=None, xm=None, ym=None, xxm=None, yym=None, domain=None)

  Return 2D grid arrays with corner points.

  Arguments:

  - `shp` : shape (ny,nx) of values

  Optional grid definitions:

  - `xx`, `yy` : 2D corner fields, shapes `(ny+1,nx+1)` ; if defined, these are the results

  - `xxm`, `yym` : 2D mid of cell fields, shapes `(nx,ny)` ;

  - `x`, `y` : 1D corner points, shapes `(nx+1)` and `(ny+1)`; used to define 2D corner fields

  - `xm`, `ym` : 1D mid of cell, shapes `(nx)` and `(ny)`; used to define 2D corners

  If none of these pairs is defined, a regular grid within the domain is assumed; if the domain is not specified, the default in `(0,nx,0,ny)`.

cso_plot.QuickPat(cc, xx=None, yy=None, x=None, y=None, xm=None, ym=None, xxm=None, yym=None, domain=None, title=None, vmin=None, vmax=None, vbounds=None, bmp={}, cbar={}, **kwargs)

  Plot 2D data as colored pattern.

  Arguments passed to `GetGrid()` :

  - `xm`, `ym` : 1D mid of cell, shapes (nx) and (ny); used to define 2D corners

  - `x`, `y` : 1D corner points, shapes (nx+1) and (ny+1); used to define 2D corner fields

  - `xxm`, `yym` : 2D mid of cell, shapes (ny,nx)

  - `xx`, `yy` : 2D corner fields, shapes (ny+1,nx+1)

  Arguments passed to `ColorbarFigure.PColor()` method:

  - `cc` : data values, shape (ny,nx)

  - `vmin`,``vmax`` : data range for coloring

  - `vbounds` : value bounds for colorbar (defines interval with same color)

  Other arguments are passed to ‘ColorbarFigure’ :

  - `figsize = (width,height)`

  - `domain=(left,right,bottom,top)` : axes extent

  - `title` : text above axes

  - `cmap = dict( 'colors'=['blue','white','red'], ncolor=9 )`

  - `cbar = dict( 'ntick'=9, extend='both', label='entity [units]' )`, or `False` to skip colorbar because it is plotted elsewhere.

  - `bmp` : map projection, see `Figure.AddAxes()`:

        bmp=dict( countries=True, raster=[30.0,30.0] )

  Return value:

  - `fig` : Figure instance

cso_plot.QuickDens(x, y, bins=10, normed=False, **kwargs)

  Density plot.

  Arguments passed to `matplotlib.pyplot.hist2d()` :

  - `x`, `y` = values

  - `bins` = number, array, or 2-element list of arrays

  - `normed` = frequency instead of numbers

  Other arguments are passed to ‘ColorbarFigure’ :

  - `figsize = (width,height)`

  - `cmap = dict( 'colors'=['blue','white','red'], ncolor=9 )`

  - `cbar = dict( 'ntick'=9, extend='both', label='entity [units]' )`

  Return value:

  - `fig` : Figure instance