Documentation page for utils/plot.py

Only some functions from this module are documented. The other undocumented functions are intended as private functions, not to be exposed to the user.

Plotting Functions.

Author: guangzhi XU (xugzhi1987@gmail.com) Update time: 2020-07-22 09:27:30.

utils.plot.plot2(var, method, ax, legend='global', xarray=None, yarray=None, title=None, latlon=True, latlongrid=False, fill_color='0.8', legend_ori='horizontal', clean=False, iscartopy=True, fix_aspect=True, verbose=True)

A helper function for quickly create 2D plots

Parameters:
  • var (NCVAR or ndarray) – variable to plot. At least 2D.
  • method – plotting method, could be an instance of Boxfill, Isofill.
  • ax – matplotlib axis obj.
Keyword Arguments:
 
  • legend (str) – location of colorbar. Could be: ‘global’: all subplots share the colorbar of the 1st subplot in figure. or ‘local’: each subplot in figure uses its own colorbar.
  • xarray (ndarray) – 1d array, the array values for the x-axis. If None, use the int indices for the x-dimension.
  • yarray (ndarray) – 1d array, the array values for the y-axis. If None, use the int indices for the y-dimension.
  • title (str) – title to plot at subtitle. If None, plot only an alphabetical index.
  • latlon (bool) – plot lat/lon axis labels or not.
  • latlongrid (bool) – plot lat/lon grid lines or not.
  • fill_color – color to fill continent or masked regions.
  • legend_ori (str) – ‘horizontal’ or ‘vertical’, colorbar orientation.
  • clean (bool) – if True, omit axis labels, colorbar, subtitle, continents, boundaries etc.. Useful to overlay plots.
  • iscartopy (bool) – plot using cartopy or not. Usually used to force plot as a normal 2d plot instead of geographical plot using cartopy.
  • fix_aspect (bool) – passed to the cartopy plotting function (e.g. contourf()) for control of aspect ratio. NOTE: needs to be deprecated.
utils.plot.plotAR(ardf, ax, lonax)

Helper function to plot the regions and axes of ARs

Parameters:
  • ardf (pandas.DataFrame) – table containing AR records.
  • ax (matplotlib axis) – axis to plot onto.
  • lonax (ndarray) – 1d array of the longitude axis the plot is using.
utils.plot.plotARTrack(arlist, latax, lonax, ax, full=False, label=None, linestyle='solid', marker=None)

Plot AR tracks

Parameters:
  • arlist (list) – list of AR objects to plot.
  • latax,lonax (ndarray) – 1darrays giving latitude- and longitude- coordinates of the plotting domain.
  • ax (matplotlib.axis) – axis to plot onto.
Keyword Arguments:
 
  • full (bool) – if True, plot tracks of an AR from its entire lifecycle. if False, plot only the track of the last time step.
  • label (str or None) – type of label to label tracks. ‘id’: label with AR id. ‘time’: label with time stamp. None: don’t put label.
  • linestyle (str) – line style to plot the tracks.
  • marker (str) – marker to plot track axes.
class utils.plot.Boxfill(vars, zero=1, split=2, max_level=None, min_level=None, ql=None, qr=None, cmap=None, verbose=True)
__init__(vars, zero=1, split=2, max_level=None, min_level=None, ql=None, qr=None, cmap=None, verbose=True)

Return an isofill object with specified color scheme.

Parameters:

vars – one or a list of variables, from which the <minlevel> and <maxlevel> is obtained. If <vars> has more than 1 variables, then function calculates the minimum and maximum of all variables, thus the color legend would be unified for all subplots. Note that if <max_level> and/or <min_level> are given, they will override the maximum/minimal levels derived from <vars>.

Keyword Arguments:
 
  • zero (int) – controls 0 in created <levels>: -1: 0 is NOT allowed to be a level; 1: 0 is permitted to be a level; 2: 0 forced to be a level.
  • split (int) –

    int, control behavior of negative and positive values 0: Do not split negatives and positives, map onto entire range of [0,1]; 1: split only when vmin<0 and vmax>0, otherwise map onto entire range of [0,1];

    If split is to be applied, negative values are mapped onto first half [0,0.5], and postives onto second half (0.5,1].
    2: force split, if vmin<0 and vmax>0, same as <split>==1;
    If vmin<0 and vmax<0, map onto 1st half [0,0.5]; If vmin>0 and vmax>0, map onto 2nd half (0.5,1].
  • max_level,min_level (float) – the max/min limits to be plotted out, values outside the range will be grouped into the last level intervals on both ends.
  • ql,qr (float) –

    extreme percentiles for the lower and upper boundaries. Could be one of the values in the list:

    percents=[0.001,0.005,0.01,0.025,0.05,0.1]

    E.g. ql=0.001; qr=0.005 means that the 0.1% percentile will be set to the minimum level; 0.005% (from the right most, or 99.95% from the left most) percentil will be set to the maximum level.

    If both <ql> and <min_level> are given, use <min_level>. If both <qr> and <max_level> are given, use <max_level>.

  • cmap

    specify a color map. Could be: 1) None, a default blue-white-red (bwr) color map will be created. 2) a matplotlib cmap obj. 3) a string name of a matplotlib cmap obj, to list of few:

    ’bwr’: blue-white-red ‘RdBu’: darkred-white-blue ‘RdYlBu’: red-yellow-white-blue ‘RdYlGn’: red-yellow-white-green ‘spectral’: purple-yellow-cyan-blue ‘seismic’: darkblue-white-darkred ‘jet’: rainbow darkblue-darkred ‘rainbow’: rainbow purple-red

    Append ‘_r’ to get the reversed colormap.

Note

<minlevel> and <maxlevel> are better derived using numpy.min() and numpy.max(). MV.min() and MV.max() may have problems. Iso levels are computed using vcs function (mkscale()), and a matplotlib colormap is created (if not given), and the colormap will be changed so positive/negative splits (if required) is achieved.

Update time: 2015-04-27 14:55:33

class utils.plot.Isofill(vars, num=15, zero=1, split=2, max_level=None, min_level=None, ql=None, qr=None, cmap=None, verbose=True)
__init__(vars, num=15, zero=1, split=2, max_level=None, min_level=None, ql=None, qr=None, cmap=None, verbose=True)

Return an isofill object with specified color scheme.

Parameters:

vars – one or a list of variables, from which the <minlevel> and <maxlevel> is obtained. If <vars> has more than 1 variables, then function calculates the minimum and maximum of all variables, thus the color legend would be unified for all subplots. Note that if <max_level> and/or <min_level> are given, they will override the maximum/minimal levels derived from <vars>.

Keyword Arguments:
 
  • Num (int) – is the (maximum) number of isoline levels;
  • zero (int) – controls 0 in created <levels>: -1: 0 is NOT allowed to be a level; 1: 0 is permitted to be a level; 2: 0 forced to be a level.
  • split (int) –

    int, control behavior of negative and positive values 0: Do not split negatives and positives, map onto entire range of [0,1]; 1: split only when vmin<0 and vmax>0, otherwise map onto entire range of [0,1];

    If split is to be applied, negative values are mapped onto first half [0,0.5], and postives onto second half (0.5,1].
    2: force split, if vmin<0 and vmax>0, same as <split>==1;
    If vmin<0 and vmax<0, map onto 1st half [0,0.5]; If vmin>0 and vmax>0, map onto 2nd half (0.5,1].
  • max_level,min_level (float) – the max/min limits to be plotted out, values outside the range will be grouped into the last level intervals on both ends.
  • ql,qr (float) –

    extreme percentiles for the lower and upper boundaries. Could be one of the values in the list:

    percents=[0.001,0.005,0.01,0.025,0.05,0.1]

    E.g. ql=0.001; qr=0.005 means that the 0.1% percentile will be set to the minimum level; 0.005% (from the right most, or 99.95% from the left most) percentil will be set to the maximum level.

    If both <ql> and <min_level> are given, use <min_level>. If both <qr> and <max_level> are given, use <max_level>.

  • cmap

    specify a color map. Could be: 1) None, a default blue-white-red (bwr) color map will be created. 2) a matplotlib cmap obj. 3) a string name of a matplotlib cmap obj, to list a few:

    ’bwr’: blue-white-red ‘RdBu’: darkred-white-blue ‘RdYlBu’: red-yellow-white-blue ‘RdYlGn’: red-yellow-white-green ‘spectral’: purple-yellow-cyan-blue ‘seismic’: darkblue-white-darkred ‘jet’: rainbow darkblue-darkred ‘rainbow’: rainbow purple-red

    Append ‘_r’ to get the reversed colormap.

Note

<minlevel> and <maxlevel> are better derived using numpy.min() and numpy.max(). MV.min() and MV.max() may have problems. Iso levels are computed using vcs function (mkscale()), and a matplotlib colormap is created (if not given), and the colormap will be changed so positive/negative splits (if required) is achieved.

Update time: 2015-04-27 14:55:33

class utils.plot.Plot2D(var, method, ax=None, xarray=None, yarray=None, title=None, latlon=True, latlongrid=False, legend='global', legend_ori='horizontal', clean=False)
__init__(var, method, ax=None, xarray=None, yarray=None, title=None, latlon=True, latlongrid=False, legend='global', legend_ori='horizontal', clean=False)

Utility class for 2D plots

Parameters:
  • var (NCVAR or ndarray) – variable to plot. At least 2D.
  • method – plotting method, could be an instance of Boxfill, Isofill.
Keyword Arguments:
 
  • ax – matplotlib axis obj. If None, create a new.
  • xarray (ndarray) – 1d array, the array values for the x-axis. If None, use the int indices for the x-dimension.
  • yarray (ndarray) – 1d array, the array values for the y-axis. If None, use the int indices for the y-dimension.
  • title (str) – title to plot at subtitle. If None, plot only an alphabetical index.
  • latlon (bool) – plot lat/lon axis labels or not.
  • latlongrid (bool) – plot lat/lon grid lines or not.
  • legend (str) – location of colorbar. Could be: ‘global’: all subplots share the colorbar of the 1st subplot in figure. or ‘local’: each subplot in figure uses its own colorbar.
  • legend_ori (str) – ‘horizontal’ or ‘vertical’, colorbar orientation. clean (bool): if True, omit axis labels, colorbar, subtitle, continents, boundaries etc.. Useful to overlay plots.
classmethod checkBasemap(var, xarray, yarray)

Check variable should be plotted using basemap or not

getGrid()

Get lat/lon grid info from data

classmethod getSlab(var)

Get a 2D slab from variable

Parameters:
  • var (NCVAR or ndarray) – nd variable. If is transient variable, try
  • slice its 1st time point. If numpy.ndarray, try to take a slab (to) –
  • its last 2 dimensions. (from) –
Returns:

result (ndarray) – a 2d slab from input <var> to plot.

class utils.plot.Plot2Cartopy(var, method, ax, legend='global', title=None, xarray=None, yarray=None, latlon=True, latlongrid=False, fill_color='0.8', legend_ori='horizontal', clean=False, fix_aspect=False)
classmethod checkBasemap(var, xarray, yarray)

Check variable should be plotted using basemap or not

getGrid()

Get lat/lon grid info from data

classmethod getSlab(var)

Get a 2D slab from variable

Parameters:
  • var (NCVAR or ndarray) – nd variable. If is transient variable, try
  • slice its 1st time point. If numpy.ndarray, try to take a slab (to) –
  • its last 2 dimensions. (from) –
Returns:

result (ndarray) – a 2d slab from input <var> to plot.