unox.plotting

Attributes

title_font_size

Functions

plot_extent(dataset, **kwargs)

Plot the geographic extent of a dataset.

plot_lats_lons(dataset[, padding])

Plot the latitude/longitude grid of a dataset.

map_ax(xr_arr, ax[, plt_title, cmap, cbar_max, ...])

Plot a geographic map from an xarray DataArray.

plot_var_maps(dataset[, vars, restrict_lat_lon_to, ...])

Plot maps for one or more variables in a dataset.

select_time(xr_data[, start_date, end_date, interval, ...])

Select a time slice from an xarray dataset.

plot_run_analysis(dataset[, start_date, interval, ...])

Compare a model run to the truth with maps and optional correlation plots.

plot_comparison(a_xr_arr, b_xr_arr[, ax, plt_title, ...])

Plot a comparison of two arrays using a 2D histogram.

corr_plot(dataset[, x_vars, y_vars, axs, ...])

Create correlation plots between specified variables.

plot_epochs_logs(dataset[, vars, axs, plt_title])

Plot training epoch logs for a prediction dataset.

make_colorbar(fig, cb_ax, cb_label[, num_ticks, ...])

Create a colorbar for the given figure and axis.

plot_hist(data_arrs[, ax, n_bins, ax_label, ylabel, ...])

Plot a histogram of one or more data arrays.

compare_input_vars([input_a_dict, input_b_dict, ...])

Compare two input variables and optionally plot their differences.

plot_BaW(vars, datasets[, ds_kwargs, axs, violin])

Plot box-and-whisker (or violin) plots for specified variables.

BaW_label(u_arr[, label_with, var, one_dataset])

Assemble a label for a box-and-whisker plot.

Module Contents

unox.plotting.title_font_size = 20
unox.plotting.plot_extent(dataset, **kwargs)[source]

Plot the geographic extent of a dataset.

Create a Robinson projection map showing the min/max latitude and longitude of the dataset.

Parameters:

  • dataset (str, xarray.Dataset, xarray.DataArray) – The dataset for which to plot the latitude/longitude extent.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to uarray().

Returns:

fig – The figure object containing the plot.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_extent('inputfiles/no2_2019_JFM/no2_2019_JFM.nc')
>>> fig = plot_extent('no2_2019_JFM', is_input_set=True)
unox.plotting.plot_lats_lons(dataset, padding=0.1, **kwargs)[source]

Plot the latitude/longitude grid of a dataset.

Create a checkerboard map showing the latitude and longitude resolution of the dataset.

Parameters:

  • dataset (str, xarray.Dataset, xarray.DataArray) – The dataset for which to plot the latitude and longitude grid.

  • padding (float, optional) – The padding (in a fraction of total extent) to add to the extent of the map. Default is 0.1.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to uarray().

Returns:

fig – The figure object containing the plot.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_lats_lons('inputfiles/no2_2019_JFM/no2_2019_JFM.nc')
>>> fig = plot_lats_lons('no2_2019_JFM', is_input_set=True)
unox.plotting.map_ax(xr_arr, ax, plt_title=None, cmap=pplt.Colormap('Fire'), cbar_max=None, cbar_min=None, cb_ext='neither', padding=0.1, **kwargs)[source]

Plot a geographic map from an xarray DataArray.

Create a map of the provided xarray DataArray on the given axes using the latitude and longitude coordinates from the data.

Parameters:

  • xr_arr (xarray.DataArray) – The xarray data to plot. Must not have a time dimension.

  • ax (matplotlib.axes.Axes) – The axes on which to plot the data.

  • plt_title (str, optional) – The title for the plot. Default is None.

  • cmap (matplotlib.colors.Colormap, optional) – The colormap to use for the plot. Default is pplt.cm.Fire.

  • cbar_max (float, optional) – Maximum value for the colorbar. When None, it uses the max value in the data. Default is None.

  • cbar_min (float, optional) – Minimum value for the colorbar. When None, it uses the min value in the data. Default is None.

  • cb_ext (str, optional) – How to extend the ends of the colorbar. Can be ‘neither’, ‘both’, ‘min’, or ‘max’. Default is ‘neither’.

  • padding (float, optional) – The padding (fraction of total extent) to add to the map extent. Default is 0.1.

  • **kwargs (keyword arguments) – Additional keyword arguments accepted to facilitate wrapper functions.

Returns:

  • this_map_ax (matplotlib.axes.Axes) – The axes object containing the plot.

  • clrbar_label (str) – The label for the colorbar containing the variable name and units.

Examples

>>> import proplot as pplt
>>> fig, axs = pplt.subplots(nrows=1, ncols=2, proj='cyl')
>>> this_xr = uarray('no2_2019_JFM', is_input_set=True).xr['no2']
>>> this_xr = this_xr.sel(time='2019-01-02').squeeze(drop=True)
>>> this_ax, cb_label = map_ax(this_xr, axs[0])
unox.plotting.plot_var_maps(dataset, vars=['nox'], restrict_lat_lon_to=None, ens_mem=None, avg_over=True, sum_over=False, add_title=True, add_clrbar=True, **kwargs)[source]

Plot maps for one or more variables in a dataset.

A wrapper around map_ax() that creates a map for each specified variable.

Parameters:

  • dataset (uarray, str, xarray.Dataset, xarray.DataArray) – The dataset for which to plot the specified variables.

  • vars (str, list, optional) – The name(s) of the variable(s) to plot from the dataset. Default is [‘nox’].

  • restrict_lat_lon_to (str, xr.DataArray, None, optional) – Path to a netCDF file to restrict the latitude and longitude range. If None, the entire dataset is used. Default is None.

  • ens_mem (int, None, optional) – The ID of the ensemble member to plot. If None, the dataset is assumed not to have multiple ensemble members. Default is None.

  • avg_over (bool, optional) – Whether to average over all time steps. Cannot be True at the same time as sum_over. Default is True.

  • sum_over (bool, optional) – Whether to sum over all time steps. Cannot be True at the same time as avg_over. Default is False.

  • add_title (bool, optional) – Whether to add a title to the figure. Default is True.

  • add_clrbar (bool, optional) – Whether to add a colorbar to each subplot. Default is True.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to uarray, select_time(), set_fig_row_col(), and map_ax().

Returns:

fig – The figure object containing the plot.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_var_maps('no2_example_run', is_predict=True, vars=['no2_pred'], datetime='2019-06-01', interval='30D', avg_over=True)
unox.plotting.select_time(xr_data, start_date=None, end_date=None, interval=None, avg_over=False, sum_over=False, **kwargs)[source]

Select a time slice from an xarray dataset.

Either select a single time slice, average over a time period, or sum over the entire available time dimension to return an xarray without a time dimension.

Parameters:

  • xr_data (xarray.Dataset, xarray.DataArray) – The xarray data to plot. Must have a time dimension.

  • start_date (str, None, optional) – First date and time to select from the data file. Default is None.

  • end_date (str, None, optional) – Last date and time to select from the data file. Default is None.

  • interval (str, numpy.timedelta64, None, optional) – If provided and end_date is None, calculates end_date based on this interval. If a string, must be in the format XT where X is an integer and T is the unit (D for days, M for months, or Y for years). Default is None.

  • avg_over (bool, optional) – Whether to average over all time steps. Cannot be True at the same time as sum_over. Default is False.

  • sum_over (bool, optional) – Whether to sum across all time steps. Cannot be True at the same time as avg_over. Default is False.

  • **kwargs (keyword arguments) – Additional keyword arguments accepted to facilitate wrapper functions.

Returns:

  • xr_sel_time (xarray.Dataset, xarray.DataArray) – The input xarray over the specified time interval. If either avg_over or sum_over is True, the return will not have a time dimension.

  • title_segment (str) – A segment of the title string for the plot with time information.

Examples

>>> xr_data = uarray('no2_2019_JFM', is_input_set=True).xr
>>> xr_sel_time, title_segment = select_time(xr_data, datetime='2019-01-15')
unox.plotting.plot_run_analysis(dataset, start_date='2019-01-02', interval='1Y', avg_over=True, restrict_lat_lon_to=None, ens_mem=None, add_corr_plots=True, stage1_only=False, clr_bar_scale=0.5, clr_map=pplt.Colormap('Balance'), **kwargs)[source]

Compare a model run to the truth with maps and optional correlation plots.

Create a set of maps comparing the truth and model predictions (stages 1 and 2), and optionally add correlation plots. If both stages and correlations are plotted, the figure will have 9 subplots: 1. ‘Truth’ map 2. Stage 1 prediction map 3. Stage 2 prediction map 4. Difference between ‘Truth’ and Stage 1 map 5. Difference between ‘Truth’ and Stage 2 map 6. Difference between Stage 1 and Stage 2 map 7. Correlation plot between ‘Truth’ and Stage 1 8. Correlation plot between ‘Truth’ and Stage 2 9. Correlation plot between Stage 1 and Stage 2

Parameters:

  • dataset (str, xarray.Dataset, xarray.DataArray, uarray) – The dataset for which to make comparison maps. Must be a predictions dataset.

  • start_date (str, None, optional) – First date and time to select from the data file. Default is None.

  • interval (str, numpy.timedelta64, None, optional) – If provided and end_date is None, calculate end_date based on this interval. If a string, it must be in the format XT where X is an integer and T is the unit (D, M, or Y). Default is None.

  • avg_over (bool, optional) – Whether to average over all time steps. Default is True.

  • restrict_lat_lon_to (str, xr.DataArray, None, optional) – Path to a netCDF file to restrict the latitude and longitude range. If None, the entire dataset is used. Default is None.

  • ens_mem (int, None, optional) – The ID of the ensemble member to plot. If None, the dataset is assumed not to have multiple ensemble members. Default is None.

  • add_corr_plots (bool, optional) – Whether to add a row of correlation plots to the figure. Default is True.

  • stage1_only (bool, optional) – If True, produce graphs only for stage 1. If False, produce graphs for both stage 1 and stage 2. Default is False.

  • clr_bar_scale (float, optional) – Scale factor for the colorbar, between 0 and 1. Default is 0.5.

  • clr_map (matplotlib.colors.Colormap, optional) – The colormap to use for the map plots. Default is pplt.cm.Balance.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to select_time(), map_ax(), and corr_plot().

Returns:

fig – The figure object containing the plots.

Return type:

matplotlib.figure.Figure

Examples

>>> fig = plot_run_analysis('no2_example_run', year=2019, datetime='2019-01-02',         ...     avg_over='364D', restrict_lat_lon_to='../datafiles/sample_data/nox_2019_t106_US.nc', add_corr_plots=True)
unox.plotting.plot_comparison(a_xr_arr, b_xr_arr, ax=None, plt_title=None, a_label=None, b_label=None, cmap=pplt.Colormap('viridis'), set_under_val=1, hist_params={'bins': 100, 'vmax': 1000, 'vmin': 10}, log_scale=True, **kwargs)[source]

Plot a comparison of two arrays using a 2D histogram.

Create a correlation plot between the values of the two provided arrays.

Parameters:

  • a_xr_arr (xarray.DataArray, numpy.ndarray) – The first array to compare.

  • b_xr_arr (xarray.DataArray, numpy.ndarray) – The second array to compare.

  • ax (matplotlib.axes.Axes, optional) – The axes on which to plot the data. If None, a new figure is created. Default is None.

  • plt_title (str, optional) – The title for the plot. Default is None.

  • a_label (str, optional) – The label to use for the first array.

  • b_label (str, optional) – The label to use for the second array.

  • cmap (matplotlib.colors.Colormap, optional) – The colormap to use for the plot. Default is pplt.cm.viridis.

  • set_under_val (float, optional) – The value below which the colormap is set to white. Default is 1.

  • hist_params (dict, optional) – Parameters for the 2D histogram. Default is {‘bins’: 100, ‘vmax’: 1000, ‘vmin’: 10}.

  • log_scale (bool, optional) – Whether to use a logarithmic scale for the histogram. Default is True.

  • **kwargs (keyword arguments) – Additional keyword arguments accepted to facilitate wrapper functions.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the plot. Returned if ax is None.

  • q (QuadMesh) – The QuadMesh object created by the 2D histogram. Returned if ax is given.

unox.plotting.corr_plot(dataset, x_vars=['pred'], y_vars=['truth'], axs=None, restrict_lat_lon_to=None, ens_mem=None, **kwargs)[source]

Create correlation plots between specified variables.

Create a heatmap correlation plot with the specified variables on each axis using data from the given dataset, filtering by datetime, averaging period, and optional latitude/longitude restrictions.

Parameters:

  • dataset (str, uarray, xarray.Dataset, xarray.DataArray) – The dataset from which to get the data for the correlation plot.

  • x_vars (list, str, optional) – The variable(s) to plot on the x-axis. Can be truth, pred, pred_s2, or any variable in the dataset. Default is [‘pred’].

  • y_vars (list, str, optional) – The variable(s) to plot on the y-axis. Can be truth, pred, pred_s2, or any variable in the dataset. Default is [‘truth’].

  • axs (list, matplotlib.axes.Axes, None, optional) – The axes on which to plot the data. If None, a new figure is created. Default is None.

  • restrict_lat_lon_to (str, xr.DataArray, None, optional) – Path to a netCDF file to restrict the latitude and longitude range. If None, the entire dataset is used. Default is None.

  • ens_mem (int, None, optional) – The ID of the ensemble member to plot. If None, the dataset is assumed not to have multiple ensemble members. Default is None.

  • **kwargs (dict) – Additional keyword arguments to pass to select_time() and plot_comparison().

Returns:

  • fig (matplotlib.figure.Figure) – If no axes were given, return the figure object containing the plot.

  • fig_q (QuadMesh) – If axes were given, return the QuadMesh object created by the 2D histogram.

Examples

>>> fig = corr_plot('no2_example_run', is_predict=True, x_ax='pred', y_ax='truth')
unox.plotting.plot_epochs_logs(dataset, vars=None, axs=None, plt_title=None, **kwargs)[source]

Plot training epoch logs for a prediction dataset.

Create a line plot showing how specified metrics changed across training epochs.

Parameters:

  • dataset (str, xarray.Dataset, xarray.DataArray, uarray) – The dataset for which to plot epoch logs. Must be a predictions dataset.

  • vars (str, list, None, optional) – The variables to plot. Each variable is plotted on its own axis. If None, all available variables are plotted. Default is None (which plots all variables).

  • axs (matplotlib.axes.Axes, None, optional) – The axes on which to plot the data. If None, a new figure is created. Default is None.

  • plt_title (str, optional) – The title for the plot. Default is None.

  • **kwargs (keyword arguments) – Additional keyword arguments accepted to facilitate wrapper functions.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the plot. Returned if axs is None.

  • axs (matplotlib.axes.Axes) – The axes containing the plot. Returned if axs was provided.

unox.plotting.make_colorbar(fig, cb_ax, cb_label, num_ticks=9, cb_loc='r', cb_extend='neither', **kwargs)[source]

Create a colorbar for the given figure and axis.

Parameters:

  • fig (matplotlib.figure.Figure) – The figure on which to add the colorbar.

  • cb_ax (cartopy.mpl.geocollection.GeoQuadMesh) – The geo quad mesh on which to add the colorbar.

  • cb_label (str) – The label for the colorbar.

  • num_ticks (int, optional) – The number of ticks for the colorbar. Default is 9.

  • cb_loc (str, optional) – The location of the colorbar. Default is ‘r’.

  • cb_extend (str, optional) – How to extend the ends of the colorbar. Can be ‘neither’, ‘both’, ‘min’, or ‘max’. Default is ‘neither’.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to colorbar(), such as the rows tuple.

Returns:

cbar – The generated colorbar.

Return type:

matplotlib.colorbar.Colorbar

Examples

>>> fig, axs = pplt.subplots(nrows=3, ncols=3)
>>> n_rows_maps = 2
>>> cbar = make_colorbar(fig, axs, cb_label='NOx emissions (kg/m2/s)', rows=(1, n_rows_maps))
unox.plotting.plot_hist(data_arrs, ax=None, n_bins=100, ax_label='NOx emissions (kg/m2/s)', ylabel='Frequency', plt_title=None, log_scale=False)[source]

Plot a histogram of one or more data arrays.

Create a histogram of the given data on the provided axis, or create a new figure and axis if none is provided. Each array in data_arrs is plotted as a separate histogram.

Parameters:

  • data_arrs (list, numpy.ndarray, xr.DataArray) – The array(s) to plot.

  • ax (matplotlib.axes.Axes, None, optional) – The axes on which to plot the histogram. If None, a new figure and axes are created. Default is None.

  • n_bins (int, optional) – The number of bins to use for the histogram. Default is 100.

  • ax_label (str, optional) – The label for the x-axis. Default is ‘NOx emissions (kg/m2/s)’.

  • ylabel (str, optional) – The label for the y-axis. Default is ‘Frequency’.

  • plt_title (str, optional) – The title of the plot. Default is None.

  • log_scale (bool, optional) – If True, the y-axis will be set to a logarithmic scale. Default is False.

Returns:

fig or ax – The figure or axes containing the histogram.

Return type:

matplotlib.figure.Figure or matplotlib.axes.Axes

Examples

>>> data_arr1 = uarray('nox_2019_JFM', is_input_set=True).xr['no2'].values
>>> data_arr2 = uarray('nox_2019_JFM', is_input_set=True).xr['no2_s2'].values
>>> fig = plot_hist(data_arr1)

>>> fig, axs = pplt.subplots(nrows=2, ncols=1)
>>> axs[0] = plot_hist([data_arr1, data_arr2], ax=axs[0], n_bins=50, plt_title='Histogram of NO2 emissions, both stages')
unox.plotting.compare_input_vars(input_a_dict={'input_set': 'no2_2019_JFM', 'year': 2019, 'var': 'no2'}, input_b_dict={'input_set': 'no2_2019_JFM', 'year': 2019, 'var': 'no2_s2'}, abs_tolerance=2e-05, restrict_lat_lon_to=None)[source]

Compare two input variables and optionally plot their differences.

Parameters:

  • input_a_dict (dict, optional) – Dictionary containing the parameters for the first input variable. Must contain ‘input_set’, ‘year’, and ‘var’.

  • input_b_dict (dict, optional) – Dictionary containing the parameters for the second input variable. Must contain ‘input_set’, ‘year’, and ‘var’.

  • abs_tolerance (float, optional) – The absolute tolerance for comparing the input files. Default is 2e-5.

  • restrict_lat_lon_to (str, xr.DataArray, None, optional) – Path to a netCDF file to restrict the latitude and longitude range. If None, the entire dataset is used. Default is None.

Returns:

  • None – If the input files match within the given tolerance.

  • fig (matplotlib.figure.Figure) – If the input files differ more than the given tolerance, a figure is returned.

Examples

>>> fig = compare_input_vars(
...     {
...         'input_set': 'no2_2019_JFM',
...         'year': 2019,
...         'var': 'no2',
...     },
...     {
...         'input_set': 'no2_2019_JFM',
...         'year': 2019,
...         'var': 'no2_s2',
...     },
...     restrict_lat_lon_to='../datafiles/sample_data/nox_2019_t106_US.nc',
... )
unox.plotting.plot_BaW(vars, datasets, ds_kwargs=None, axs=None, violin=False, **kwargs)[source]

Plot box-and-whisker (or violin) plots for specified variables.

Create a box-and-whisker plot (or optional violin plot) of the specified variables from one or more datasets.

Parameters:

  • vars (list, str) – The variable(s) to plot on the x-axis/axes. Can be R2, RMSE, or any variable in the dataset.

  • datasets (list, str, uarray, xarray.Dataset, xarray.DataArray) – The dataset(s) from which to get the data for the plot.

  • ds_kwargs (list, dict, optional) – Dictionaries of keyword arguments to specify the format of each plot. Default is None.

  • axs (list, matplotlib.axes.Axes, None, optional) – The axes on which to plot the data. If None, a new figure is created. Default is None.

  • violin (bool, optional) – Whether to make a violin plot instead of a box-and-whisker plot. Default is False.

  • **kwargs (dict) – Additional keyword arguments to pass to set_fig_row_col().

Returns:

  • fig (matplotlib.figure.Figure) – If no axes were provided, return the figure object containing the plot.

  • axs (matplotlib.axes.Axes) – If axes were provided, return those axes with the plots on them.

Examples

>>> fig = plot_BaW(
...     ['R2', 'RMSE'],
...     '_ZFI_ensemble_run',
...     ds_kwargs=[
...         {
...             'is_predict': True,
...             'start_date': '2019-01-02',
...             'interval': '1Y',
...             'restrict_lat_lon_to': 'datafiles/sample_data/nox_2019_t106_US.nc',
...         },
...     ]
... )
unox.plotting.BaW_label(u_arr, label_with=None, var=None, one_dataset=False, **kwargs)[source]

Assemble a label for a box-and-whisker plot.

Construct a label for a box-and-whisker plot based on metadata from a uarray, the requested components in label_with, and any formatting kwargs.

Parameters:

  • u_arr (uarray) – The uarray object from which to derive label metadata.

  • label_with (list, None, optional) – Components to include in the label (e.g., [‘name’, ‘size’]). Default is None, which uses [‘name’, ‘size’].

  • var (str, optional) – The variable name to use when computing label components like size.

  • one_dataset (bool, optional) – Whether the plot is for a single dataset. Default is False.

  • **kwargs (dict) – Additional keyword arguments passed to format_sci_notation().

Returns:

The formatted label.

Return type:

str

Examples

>>> BaW_label(
...     uarray('no2_example_run', is_predict=True),
...     label_with=['name', 'size'],
...     var='nox_pred',
...     one_dataset=False,
... )
'no2_example_run (n=4892160)'