emc2.plotting (emc2.plotting)¶

This module contains routines for visualizing simulated radar data from EMC^2.

SubcolumnDisplay(model[, lat_sel, lon_sel])

This class contains modules for displaying the generated subcolumn parameters as quicklook plots.

class emc2.plotting.SubcolumnDisplay(model, lat_sel=None, lon_sel=None, **kwargs)[source]¶

This class contains modules for displaying the generated subcolumn parameters as quicklook plots. It is inherited from ACT’s Display object. For more information on the Display object and its attributes and parameters, click here. In addition to the methods in Display, SubcolumnDisplay has the following attributes and methods: The plotting dataset is automatically cropped to include only single lat and lon coordinates in case of a regional output, but can always be replaced with different coordinates using the internal methods. Note that there is no dedicated option to plot subcolumns vs. lat or lon, since subcolumns at a given grid cell are independent of subcolumns attributed to other neighboring grid cells. Note: if older version of ACT are installed (e.g., 0.2.4), “_ds” should be replaced with “_arm”.

Examples

This example makes a four panel plot of 4 subcolumns of EMC^2 simulated reflectivity:

$ model_display = emc2.plotting.SubcolumnDisplay(my_model, subplot_shape=(2, 2), figsize=(30, 20))
$ model_display.plot_subcolumn_timeseries('sub_col_Ze_cl_strat', 1, subplot_index=(0, 0))
$ model_display.plot_subcolumn_timeseries('sub_col_Ze_cl_strat', 2, subplot_index=(1, 0))
$ model_display.plot_subcolumn_timeseries('sub_col_Ze_cl_strat', 3, subplot_index=(0, 1))
$ model_display.plot_subcolumn_timeseries('sub_col_Ze_cl_strat', 4, subplot_index=(1, 1))

Attributes:

model: emc2.core.Model: The model object containing the subcolumn data to plot.

Parameters:

model: emc2.core.Model: The model containing the subcolumn data to plot.
lat_sel: float, int, or None: Relevant only if a latitude dimension exists in dataset (model output file). if float, then specifying the latitude value for which to crop the model xr.Dataset for plotting (using the nearest value). if int, then specifying the index to crop. if None, then using index 0 to prevent issues.
lon_sel: float, int, or None: Relevant only if a lonitude dimension exists in dataset (model output file). if float, then specifying the lonitude value for which to crop the model xr.Dataset for plotting (using the nearest value). if int, then specifying the index to crop. if None, then using index 0 to prevent issues.
Additional keyword arguments are passed into act.plotting.plot.Display’s constructor.

calc_mean_and_sd(variable, use_geom_mean=False, axis=None)[source]¶

This function calculates geometric or arithmetic mean and SD of arrays.

Parameters:

variable: np.ndarray: array to use for calculation.
axis: int, tuple, or None: axis along which to calculate the mean and SD. None for calcualtion over the full array (single output value).
use_geom_mean: str or bool: if True, then using geometric mean and SD, If False, using arithmetic mean and SD.

Returns:

Mean: np.ndarray: array of calculated mean.
SD: np.ndarray: array of calculated SD.

change_plot_to_class_mask(cbar, class_legend=None, variable=None, cbar_label='', cmap=None, convert_zeros_to_nan=False, **kwargs)[source]¶

Updates the colorbar to show phase classification.

Parameters:

cbar: Matplotlib axes handle: colorbar handle.
class_legend: list: Class type strings in order corresponding to mask integer values. If None, using the “legend” attributes from the mask variable.
variable: str: The classification mask variable to use assuming it has a “legend” attribute Raises an error when both variable and class_legend are both None.
cbar_label: str: The colorbar label. Empty string by default.
cmap: ListedColormap object: colormap to use in the colorbar. If None, using tab20c(N), where N is the number of classes.
convert_zeros_to_nan: bool: If True, assuming that the plotted classification mask has all the zeros converted to nans, i.e., ‘convert_zeros_to_nan’ was True when the classification method was called.

Returns:

cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_column_input_q_timeseries(variable, pressure_coords=True, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, log_plot=False, Mask_array=None, hatched_mask=False, x_range=None, y_range=None, x_dateformat='%b%d-%H', x_rotation=30.0, column_no=0, **kwargs)[source]¶

Plots timeseries of subcolumn parameters for a given variable and subcolumn. In the case of a 2D (time x height) field, plotting a time-height curtain.

Parameters:

variable: str: The subcolumn variable to plot.
pressure_coords: bool: Set to true to plot in pressure coordinates, false to height coordinates.
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
log_plot: bool: Set to true to plot variable in logarithmic space.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to make them transparent.
hatched_mask: bool or str: True - masked areas show masked ‘/’ pattern, False - Masked area is transparent, str - use the str as the hatch pattern (see: https://matplotlib.org/stable/gallery/shapes_and_collections/hatch_demo.html).
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
x_dateformat: str: Date format for the x-axis.
x_rotation: float: x-axis label rotation for a date axis.
column_no: int: The column number to plot.
Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_instrument_mean_profile(instrument, variable, time_range=None, pressure_coords=True, title=None, subplot_index=(0,), log_plot=False, plot_SD=True, Xlabel=None, Mask_array=None, x_range=None, y_range=None, use_geom_mean=False, **kwargs)[source]¶

This function will plot a mean vertical profile of an instrument variable averaged over a given time period. The thick line will represent the mean profile along the given period, and the shading represents one standard deviation about the mean.

Parameters:

instrument: :py:mod:`emc2.core.Instrument`: The Instrument class that you wish to plot.
variable: str: The name of the variable to plot.
time_range: datetime64 or None: Two-element array with starting and ending of time range; use the full data range when None.
pressure_coords: bool: Set to true to plot in pressure coordinates.
title: str or None: Set the title of the plot to this string. Set to None to provide a default title
subplot_index: tuple: The index of the subplot to make the plot in.
log_plot: bool: Set to true to plot variable in logarithmic space.
plot_SD: bool: Set to True (default) in order to plot a shaded patch for mean +- SD.
Xlabel: None or str: X-axis label. Set to None to provide a default label.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to exclude them from mean and SD calculations.
x_range: tuple, list, or Non: The x range of the plot.
y_range: tuple, list, or None: The y range of the plot.
use_geom_mean: str or bool: if True, then using geometric mean and SD, If False, using arithmetic mean and SD, if “auto” then choosing based on typical variable scales (e.g., geometric for reflectivity and backscatter, and arithmetic for V_D.
kwargs

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.

plot_instrument_timeseries(instrument, variable, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, log_plot=False, Mask_array=None, hatched_mask=False, x_range=None, y_range=None, x_dateformat='%b%d-%H', x_rotation=30.0, **kwargs)[source]¶

Plots timeseries of a given instrument variable.

Parameters¶

instrument: emc2.core.Instrument: The Instrument class that you wish to plot.
variable: str: The variable to plot.
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
log_plot: bool: Set to true to plot variable in logarithmic space.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to make them transparent.
hatched_mask: bool or str: True - masked areas show masked ‘/’ pattern, False - Masked area is transparent, str - use the str as the hatch pattern (see: https://matplotlib.org/stable/gallery/shapes_and_collections/hatch_demo.html).
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
x_dateformat: str: Date format for the x-axis.
x_rotation: float: x-axis label rotation for a date axis.

Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_regridded_CF_timeseries(var_array_3D, newgrid_mid, col_index, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, x_range=None, y_range=None, x_dateformat='%b%d-%H', x_rotation=30.0, **kwargs)[source]¶

Plots timeseries of cloud fraction

Parameters:

var_array_3D: float: input variable, cloud fraction
newgrid_mid: float: vertical heights, unit: km
col_index: int: column index
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
x_dateformat: str: Date format for the x-axis.
x_rotation: float: x-axis label rotation for a date axis.
Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_regridded_SR_timeseries(var_array_4D, newgrid_mid, col_index, subcol_index, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, x_range=None, y_range=None, x_dateformat='%b%d-%H', x_rotation=30.0, **kwargs)[source]¶

Plots timeseries of cloud fraction

Parameters:

var_array_4D: float: input variable, lidar scattering ratio
newgrid_mid: float: vertical heights, unit: km
col_index: int: column index
subcol_index: int: subcolumn index
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
x_dateformat: str: Date format for the x-axis.
x_rotation: float: x-axis label rotation for a date axis.
Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.
Returns
——-
axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_single_profile(variable, time, pressure_coords=True, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, log_plot=False, Mask_array=None, hatched_mask=False, x_range=None, y_range=None, **kwargs)[source]¶

Plots the single profile of subcolumns for a given time period.

Parameters:

variable: str: The subcolumn variable to plot.
time: tuple of Datetime or str: The time step to plot. If a string, specify in the format ‘%Y-%m-%dT%H:%M:%S’
pressure_coords: bool: Set to true to plot in pressure coordinates, false to height coordinates.
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, then plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
log_plot: bool: Set to true to plot variable in logarithmic space.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to make them transparent or hatched.
hatched_mask: bool or str: True - masked areas show masked ‘/’ pattern, False - Masked area is transparent, str - use the str as the hatch pattern (see: https://matplotlib.org/stable/gallery/shapes_and_collections/hatch_demo.html).
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

plot_subcolumn_mean_profile(variable, time=None, pressure_coords=True, title=None, subplot_index=(0,), log_plot=False, plot_SD=True, Xlabel=None, Mask_array=None, x_range=None, y_range=None, use_geom_mean=False, **kwargs)[source]¶

This function will plot a mean vertical profile of a subcolumn variable for a given time period. The thick line will represent the mean profile along the subcolumns, and the shading represents one standard deviation about the mean.

Parameters:

variable: str: The name of the variable to plot.
time: tuple of Datetime or str: The time period to plot. If a string, specify in the format ‘%Y-%m-%dT%H:%M:%S’ If a 2-element array using the values within range.
pressure_coords: bool: Set to true to plot in pressure coordinates.
title: str or None: Set the title of the plot to this string. Set to None to provide a default title
subplot_index: tuple: The index of the subplot to make the plot in.
log_plot: bool: Set to true to plot variable in logarithmic space.
plot_SD: bool: Set to True (default) in order to plot a shaded patch for mean +- SD.
Xlabel: None or str: X-axis label. Set to None to provide a default label.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to exclude them from mean and SD calculations.
x_range: tuple, list, or None: The x range of the plot.
y_range: tuple, list, or None: The y range of the plot.
use_geom_mean: str or bool: if True, then using geometric mean and SD, If False, using arithmetic mean and SD, if “auto” then choosing based on typical variable scales (e.g., geometric for reflectivity and backscatter, and arithmetic for V_D.
kwargs

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.

plot_subcolumn_timeseries(variable, column_no=0, pressure_coords=True, title=None, subplot_index=(0,), colorbar=True, cbar_label=None, log_plot=False, Mask_array=None, hatched_mask=False, x_range=None, y_range=None, x_dateformat='%b%d-%H', x_rotation=30.0, **kwargs)[source]¶

Plots timeseries of subcolumn parameters for a given variable and subcolumn. In the case of a 2D (time x height) field, plotting a time-height curtain.

Parameters:

variable: str: The subcolumn variable to plot.
column_no: int: The subcolumn number to plot. By default, using the first subcolumn.
pressure_coords: bool: Set to true to plot in pressure coordinates, false to height coordinates.
title: str or None: The title of the plot. Set to None to have EMC^2 generate a title for you.
subplot_index: tuple: The index of the subplot to make the plot in.
colorbar: bool: If true, plot the colorbar.
cbar_label: None or str: The colorbar label. Set to None to provide a default label.
log_plot: bool: Set to true to plot variable in logarithmic space.
Mask_array: bool, int, or float (same dims as “variable”): Set to true or to other values greater than 0 in grid cells to make them transparent.
hatched_mask: bool or str: True - masked areas show masked ‘/’ pattern, False - Masked area is transparent, str - use the str as the hatch pattern (see: https://matplotlib.org/stable/gallery/shapes_and_collections/hatch_demo.html).
x_range: tuple, list, or None: The x range of the plot (also accepts datetime64 format).
y_range: tuple, list, or None: The y range of the plot.
x_dateformat: str: Date format for the x-axis.
x_rotation: float: x-axis label rotation for a date axis.
Additional keyword arguments are passed into matplotlib’s matplotlib.pyplot.pcolormesh.

Returns:

axes: Matplotlib axes handle: The matplotlib axes handle of the plot.
cbar: Matplotlib axes handle: The matplotlib colorbar handle of the plot.

static set_axis_label(ds, variable, max_long_name=20, use_prespec=True)[source]¶

Setting the axis label based on whether a field name is one of prespecified fields, its attributes exist, and whether these attributes are not “too long”.

Parameters:

ds: xr.Dataset: dataset containing the field for which to generate the label.
variable: str: Name of variable for which to generate axis title.
max_long_name: int: maximum length of the “long_name” attribute to include in plot
use_prespec: bool: If True, then setting axis label based on pre-specified variable names (if exist in variable name).

Returns:

axis_title: str: axis title

set_xrng(subplot_index, x_range)[source]¶

Set the Y axes limits of the subplot

Parameters:

subplot_index: tuple: The index of the subplot to set the y axes limits to.
x_range: tuple: The y range of the plot.

Returns:

set_yrng(subplot_index, y_range)[source]¶

Set the Y axes limits of the subplot

Parameters:

subplot_index: tuple: The index of the subplot to set the y axes limits to.
y_range: tuple: The y range of the plot.

Returns: