geocontour.output module

Functions for visualizing and saving output produced by geocontour

geocontour.output.plot(latitudes, longitudes, boundary=None, mask=None, contour=None, contoursearch=None, geocontour=None, vertices=None, boundingbox='all', buffer=False, grid=True, cells='default', undermask=False, showcontour=True, startcell=True, contourarrows=True, contoursearcharrows=True, fancycontoursearch=True, contoursearch_contraction=0.2, contoursearch_shift=0.25, geocontourvectors=True, emptycellcolor='lightgrey', fullcellcolor='sandybrown', undermaskcolor='slategrey', boundarycolor='tab:blue', contourcolor='olivedrab', contoursearchcolor='firebrick', geocontourcolor='olivedrab', vertexcolor='tab:cyan', gridcolor='black', lw_boundary=0.1, lw_contour=0.1, lw_contoursearch='auto', lw_geocontour=0.1, mw_contourarrows=0.5, mw_contoursearcharrows='auto', mw_vertices=0.4, features=None, title=None, labs=True, outname='plot', outdpi='high', transp=False)

Plot any/all geocontour-created elements:

  • boundary

  • mask

  • contour

  • contoursearch

  • geocontour

  • vertices

Parameters:

  • latitudes (ndarray) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray) – 1D Nx1 array of longitude points (degrees)

  • boundary (ndarray, optional) – 2D Nx2 array of latitude/longitude points (degrees) with the last point equal to the first

  • mask (ndarray, optional) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • contour (ndarray, optional) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray, optional) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

  • geocontour (ndarray, optional) – 3D Nx2x5 array defining a list of N contour cells (column 1), their edge points (columns 2,3), segment lengths (column 4), and outward unit vectors (column 5)

  • vertices (ndarray, optional) – 2D Nx2 array of latitude/longitude points (degrees)

  • boundingbox ({'all', 'boundary', 'mask', 'contour', 'contoursearch', 'geocontour'}, default='all') – select the plot element(s) to be used as x and y axis limits [default value ‘all’ uses the largest bounds from all provided elements]

  • buffer (bool, default=True) – create a 1 cell buffer on the bounding box

  • grid (bool, default=True) – show/hide the cell grid

  • cells ({'default', 'none', 'mask', 'maskedge-4', 'maskedge-8', 'contour', 'geocontour'}, default='default') –

    the plot element to be used for filling the cell grid

    default

    use first provided element, in this order: ‘geocontour’, ‘contour’, ‘mask’, ‘none’

    none

    no filled grid cells

    mask

    all mask cells

    maskedge-4

    4-connected mask edge cells

    maskedge-8

    8-connected mask edge cells

    contour

    contour cells

    geocontour

    geocontour cells

  • undermask (bool, default=False) – show/hide the mask cells independently of the cells input [allows showing a mask underlay beneath selected contour cells]

  • showcontour (bool, default=True) – show/hide the contour (if provided) [allows showing contour cells without line plot of contour]

  • startcell (bool, default=True) – show/hide the startcell (contour or contoursearch, if provided)

  • contourarrows (bool, default=True) – show/hide directional arrows on the contour (if provided)

  • contoursearcharrows (bool, default=True) – show/hide directional arrows on the contoursearch (if provided)

  • fancycontoursearch (bool, default=True) – plot the contoursearch (if provided) in a cleaner and more easily followed format

  • contoursearch_contraction (float, default=0.2) – value determining how much contoursearch “shrinks” towards contour cell edges (range 0 to 0.5)

  • contoursearch_shift (float, default=0.25) – value determining how much contoursearch shifts to avoid doubling back on itself (range 0 to 0.5)

  • geocontourvectors (bool, default=True) – show/hide outward normal vectors on the geocontour (if provided)

  • emptycellcolor (matplotlib_color, default='lightgray') – color for unmasked cells

  • fullcellcolor (matplotlib_color, default='sandybrown') – color for masked cells

  • undermaskcolor (matplotlib_color, default='slategrey') – color for mask underlay cells

  • boundarycolor (matplotlib_color, default='tab:blue') – color for boundary (if provided)

  • contourcolor (matplotlib_color, default='olivedrab') – color for contour (if provided)

  • contoursearchcolor (matplotlib_color, default='firebrickred') – color for contoursearch (if provided)

  • geocontourcolor (matplotlib_color, default='olivedrab') – color for geocontour (if provided)

  • vertexcolor (matplotlib_color, default='tab:cyan') – color for vertices (if provided)

  • gridcolor (matplotlib_color, default='black') – color for grid

  • lw_boundary (float, default=0.1) – boundary linewidth in units of grid cells (see Notes for more detail)

  • lw_contour (float, default=0.1) – contour linewidth in units of grid cells (see Notes for more detail)

  • lw_contoursearch ({'auto', float}, default='auto') – contoursearch linewidth in units of grid cells (see Notes for more detail) [i.e. ‘auto’ specifies 0.075 if fancycontoursearch = True and 0.1 if fancycontoursearch = False]

  • lw_geocontour (float, default=0.1) – geocontour linewidth in units of grid cells (see Notes for more detail)

  • mw_contourarrows (float, default=0.5) – contour arrow markerwidth in units of grid cells (see Notes for more detail)

  • mw_contoursearcharrows ({'auto', float}, default='auto') – contoursearch arrow markerwidth in units of grid cells (see Notes for more detail) [i.e. ‘auto’ specifies 0.35 if fancycontoursearch = True and 0.5 if fancycontoursearch = False]

  • mw_vertices (float, default=0.4) – vertex markerwidth in units of grid cells (see Notes for more detail)

  • features ({None, 'natural', 'borders'}, default=None) –

    display geographic features (if cartopy is installed)

    natural

    display coastlines, ocean, and lakes/rivers

    borders

    display national and state/province level boundaries

  • title (str, default=None) – the plot title

  • labs (bool, default=True) – x/y plot labels on or off [e.g. off if no associated lat/lon]

  • outname (str, default='plot') – filename/path for the saved image

  • outdpi ({'high', 'low', 'indep', float}, default='high') –

    dpi of the saved image

    high

    scale dpi high enough (36 pixels per grid cell) to see features when zooming into a single grid cell (dpi floor of 100) [for very large grids, ‘auto’ may set dpi high enough that pyplot will hang on some systems - setting outdpi = ‘low’ or entering desired dpi manually can avoid this if encountered]

    low

    scale dpi to 5 pixels per grid cell (dpi floor of 100)

    indep

    set output dpi to 200 regardless of grid size/spacing

    float

    any other entry must be a numerical value specifying desired pixels per grid cell

  • transp (bool, default=False) – set exterior of plot to transparent with text/labels/ticks/frame set to ‘dimgray’ for contrast against light and dark backgrounds (e.g. for environments in which light/dark mode may not be constant)

Return type:

None

See also

geocontour.contourutil.fancysearch, datascale.plotdatasize, datascale.plotdatadpi

Notes

  • Some inputs will only be utilized in the presence of others. For example (not exhaustive), contourcolor will have no effect if no contour is provided, mw_contourarrows will have no effect if contourarrows = False, and contoursearch_contraction will have no effect if fancycontoursearch = False.

  • All color inputs may be provided as matplotlib pre-defined colors (e.g. ‘red’ or ‘r’), hex RGB(A) strings (e.g. ‘ff0000’), or RGB(A) tuples (e.g. (1,0,0)).

  • Inputs for linewidths and markerwidths are given in units of grid cells. For example, a linewidth of 0.5 means the line will be half as wide as grid cells for the given plot and a markerwidth of 0.5 means the same. The datascale package is utilized for this functionality and the intent is to have plot features all scale and be interpretable on the plot as a default, since the primary function of plot is diagnostic. Example or publication figures may require user-altered line and marker widths, though adjustment should be simple as the inputs are all in units of the plotted grid cells.

Examples

  1. Plot a mask and the boundary used to create it

    plot(latitudes, longitudes, boundary=<boundary>, mask=<mask>, lw_boundary=0.2)

  2. Plot a contour

    plot(latitudes, longitudes, countour=<countour>, boundingbox=’contour’, buffer=True)

  3. Plot a contoursearch overlaying contour cells

    plot(latitudes, longitudes, contour=<contour>, contoursearch=<contoursearch>, showcontour=False, cells=’contour’, boundingbox=’contoursearch’, buffer=True)

  4. Plot a geocontour overlaid onto a map projection with natural features

    plot(latitudes, longitudes, geocontour=<geocontour>, cells=’geocontour’, features=’natural’)

geocontour.output.save(latitudes, longitudes, boundary=None, mask=None, contour=None, contoursearch=None, geocontour=None, vertices=None, outname='save', outtype='np', maskouttxt=False, outformat='%8.3f', outdelim=' ')

Save any/all geocontour-created elements:

  • boundary

  • mask

  • contour

  • contoursearch

  • geocontour

  • vertices

Parameters:

  • latitudes (ndarray) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray) – 1D Nx1 array of longitude points (degrees)

  • boundary (ndarray, optional) – 2D Nx2 array of latitude/longitude points (degrees) with the last point equal to the first

  • mask (ndarray, optional) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • contour (ndarray, optional) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray, optional) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

  • geocontour (ndarray, optional) – 3D Nx2x5 array defining a list of N contour cells (column 1), their edge points (columns 2,3), segment lengths (column 4), and outward unit vectors (column 5)

  • vertices (ndarray, optional) – 2D Nx2 array of latitude/longitude points (degrees)

  • outname (str, default='save') – the filename/path for the saved elements

  • outtype ({'np', 'xyz'}, default='np') –

    select the output filetype

    np

    A numpy binary file that stores each element as a separate array/object

    xyz

    An xyz format text file (lat, lon, [data])

  • maskouttxt (bool, default=False) – select to also save a mask as a (1/0) text file

  • outformat (format_str, default='%8.3f') – formatting string for latitude and longitude values (in .xyz file)

  • outdelim (str, default=' ') – delimiter string for columns in output (in .xyz file)

Return type:

None