gcpy.benchmark.modules.benchmark_models_vs_obs

Python functions to plot modeled data from 1-year fullchem benchmark simulations against observations for the year 2019. At present, only O3 plots are supported, but this can be extended in the future.

References

Author: Matt Rowlinson (York University)

Linted with PyLint and incorporated into GCPy by Bob Yantosca (GitHub: @yantosca)

Functions

find_times(obs_dataframe, start_time)

Convert timestamps in nasa ames data files to python datetime objects and set DataFrame index to the new datetime array.

get_nearest_model_data_to_obs(gc_data, ...)

Returns GEOS-Chem model data (on a cubed-sphere grid) at the grid box closest to an observation site location.

make_benchmark_models_vs_obs_plots(...[, ...])

Driver routine to create model vs.

plot_models_vs_obs(obs_dataframe, obs_label, ...)

Plots models vs.

plot_one_page(pdf, obs_dataframe, obs_label, ...)

Plots a single page of models vs.

plot_single_station(fig, rows_per_page, ...)

Plots observation data vs.

prepare_data_for_plot(obs_dataframe, ...[, ...])

Prepares data for passing to routine plot_single_frames as follows:

read_model_data(filepaths, varname[, verbose])

Reads model data from a netCDF file.

read_nas(input_file[, verbose])

Read NASA Ames data files from EBAS (https://ebas-data.nilu.no) Creates data frame of O3 values converted to ppb and dictionary with key site information (name, lat, lon, altitude)

read_observational_data(path, verbose)

Reads the observational O3 data from EBAS (taken from https://ebas-data.nilu.no/ on 15/05/2023)
gcpy.benchmark.modules.benchmark_models_vs_obs.read_nas(input_file, verbose=False)[source]

Read NASA Ames data files from EBAS (https://ebas-data.nilu.no) Creates data frame of O3 values converted to ppb and dictionary with key site information (name, lat, lon, altitude)

Parameters:

  • input_file (str) – Path to observational data file.

  • verbose (bool, optional) – Toggles verbose output on/off.

Returns:

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_site_coords (dict) – Coords (lon/lat/alt) at each site.

gcpy.benchmark.modules.benchmark_models_vs_obs.read_observational_data(path, verbose)[source]

Reads the observational O3 data from EBAS (taken from https://ebas-data.nilu.no/ on 15/05/2023)

Loops over all data files (in NASA/Ames format) within a folder and concatenates them into a single DataFrame.

Parameters:

  • path (str) – Path to the observational data dir.

  • verbose (bool) – Toggles verbose output on/off.

Returns:

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_site_coords (dict) – Coords (lon/lat/alt) at each site.

gcpy.benchmark.modules.benchmark_models_vs_obs.read_model_data(filepaths, varname, verbose=False)[source]

Reads model data from a netCDF file. Adds special handling to look for species concentrations variable names starting with either “SpeciesConcVV” or “SpeciesConc”. This is necessary for backwards compatitbility with GEOS-Chem output prior to version 14.1.0.

Parameters:

  • filepaths (list) – List of GEOS-Chem data files to read.

  • varname (str) – Variable name(s) to read.

  • verbose (bool, optional) – Toggles verbose output on/off.

Returns:

dataarray – GEOS-Chem data read from disk.

Return type:

xr.DataArray

gcpy.benchmark.modules.benchmark_models_vs_obs.find_times(obs_dataframe, start_time)[source]

Convert timestamps in nasa ames data files to python datetime objects and set DataFrame index to the new datetime array.

Parameters:

  • obs_dataframe (pd.DataFrame) – Observations from GAW sites.

  • start_time (str) – Reference start time for obs data.

Returns:

  • obs_dataframe (pd.DataFrame) – Observations (ppbv) w/ datetime index.

  • qcflag (pd.DataFrame) – Quality control info w/ datetime index.

  • start_time (str) – Reference start time for obs data.

gcpy.benchmark.modules.benchmark_models_vs_obs.get_nearest_model_data_to_obs(gc_data, gc_levels, lon_value, lat_value, alt_value, gc_cs_grid=None)[source]

Returns GEOS-Chem model data (on a cubed-sphere grid) at the grid box closest to an observation site location.

Parameters:

  • gc_data (pd.DataFrame) – Observations at each station site.

  • gc_levels (pd.DataFrame) – Metadata for model vertical levels.

  • lon_value (float) – Longitude of station site.

  • lat_value (float) – Latitude of station site.

  • alt_value (float) – Altitude of station site.

  • gc_cs_grid (xr.Dataset, optional) – Metadata for Dev cubed-sphere grid.

Returns:

dataframe – Model data closest to the station site.

Return type:

pd.DataFrame

gcpy.benchmark.modules.benchmark_models_vs_obs.prepare_data_for_plot(obs_dataframe, obs_site_coords, obs_site_name, ref_dataarray, ref_cs_grid, dev_dataarray, dev_cs_grid, gc_levels, varname='SpeciesConcVV_O3')[source]

Prepares data for passing to routine plot_single_frames as follows:

  1. Computes the mean of observations at the given station site.

  2. Returns the GEOS-Chem Ref and Dev data at the gridbox closest

    to the given station site.

  3. Creates the top-of-plot title for the given station site.

Parameters:

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_site_coords (dict) – Coords (lon/lat/alt) at each site.

  • obs_site_name (str) – Names of station sites.

  • ref_dataarray (xr.DataArray) – Data from the Ref model version.

  • ref_label (str) – Label for the Ref model data.

  • ref_cs_grid (xr.Dataset) – Metadata for Ref cubed-sphere grid.

  • dev_dataarray (xr.DataArray) – Data from the Dev model version.

  • dev_label (str) – Label for the Dev model data.

  • dev_cs_grid (xr.Dataset) – Metadata for Dev cubed-sphere grid.

  • gc_levels (pd.DataFrame) – Metadata for model vertical levels.

  • varname (str, optional) – Variable name for model data.

Returns:

  • obs_dataframe (pd.DataFrame) – Mean observational data @ station site.

  • ref_series (pd.Series) – Ref data nearest to the station site.

  • dev_series (pd.Series) – Dev data nearest to the station site.

  • subplot_title (str) – Title for the station site subplot.

  • subplot_ylabel (str) – Y-axis title for the station site subplot.

gcpy.benchmark.modules.benchmark_models_vs_obs.plot_single_station(fig, rows_per_page, cols_per_page, subplot_index, subplot_title, subplot_ylabel, obs_dataframe, obs_label, obs_site_name, ref_series, ref_label, dev_series, dev_label)[source]

Plots observation data vs. model data at a single station site.

Parameters:

  • fig (mpl.figure.Figure) – Figure object for the plot.

  • rows_per_page (int) – # of rows to plot on a page.

  • cols_per_page (int) – # of columns to plot on a page.

  • subplot_index (int) – Index of each subplot.

  • subplot_title (str) – Title for each subplot.

  • subplot_ylabel (str) – Y-axis title for each subplot.

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_site_name (str) – Name of the station site.

  • ref_series (pd.Series) – Data from the Ref model version.

  • ref_label (str) – Label for the Ref model data.

  • dev_dataarray (pd.Series) – Data from the Dev model version.

  • dev_label (str) – Label for the Dev model data.

gcpy.benchmark.modules.benchmark_models_vs_obs.plot_one_page(pdf, obs_dataframe, obs_label, obs_site_coords, obs_site_names, ref_dataarray, ref_label, ref_cs_grid, dev_dataarray, dev_label, dev_cs_grid, gc_levels, rows_per_page=3, cols_per_page=3, varname='SpeciesConcVV_O3')[source]

Plots a single page of models vs. observations.

Parameters:

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_label (str) – Label for the observational data.

  • obs_site_coords (dict) – Coords (lon/lat/alt) at each site.

  • obs_site_names (list) – Names of station sites per page.

  • ref_dataarray (xr.DataArray) – Data from the Ref model version.

  • ref_label (str) – Label for the Ref model data.

  • ref_cs_grid (str or None) – Metadata for Ref cubed-sphere grid.

  • dev_dataarray (xr.DataArray) – Data from the Dev model version.

  • dev_label (str) – Label for the Dev model data.

  • dev_cs_grid (str or None) – Metadata for Dev cubed-sphere grid.

  • gc_levels (pd.DataFrame) – Metadata for model vertical levels.

  • rows_per_page (int, optional) – Number of rows to plot on a page.

  • varname (str, optional) – Variable name for model data.

gcpy.benchmark.modules.benchmark_models_vs_obs.plot_models_vs_obs(obs_dataframe, obs_label, obs_site_coords, ref_dataarray, ref_label, dev_dataarray, dev_label, gc_levels, varname='SpeciesConcVV_O3', dst='./benchmark')[source]

Plots models vs. observations using a 3 rows x 3 column layout.

Parameters:

  • obs_dataframe (pd.DataFrame) – Observations at each station site.

  • obs_label (str) – Label for the observational data.

  • obs_site_coords (dict) – Coords (lon/lat/alt) at each site.

  • ref_dataarray (xr.DataArray) – Data from the Ref model version.

  • ref_label (str) – Label for the Ref model data.

  • dev_dataarray (xr.DataArray) – Data from the Dev model version.

  • dev_label (str) – Label for the Dev model data.

  • gc_levels (pd.DataFrame) – Metadata for model vertical levels.

  • varname (str, optional) – Variable name for model data.

  • dst (str, optional) – Destination folder for plots.

gcpy.benchmark.modules.benchmark_models_vs_obs.make_benchmark_models_vs_obs_plots(obs_filepaths, obs_label, ref_filepaths, ref_label, dev_filepaths, dev_label, varname='SpeciesConcVV_O3', dst='./benchmark', verbose=False, overwrite=False)[source]

Driver routine to create model vs. observation plots.

Parameters:

  • obs_filepaths (str or list) – Path(s) to the observational data.

  • obs_label (str) – Label for the observational data.

  • ref_filepaths (str) – Paths to the Ref model data.

  • ref_label (str) – Label for the Ref model data.

  • dev_filepaths (str) – Paths to the Dev model data.

  • dev_label (str) – Label for the Dev model data.

  • varname (str, optional) – Variable name for model data.

  • dst (str, optional) – Destination folder for plots.

  • verbose (bool, optional) – Toggles verbose output on/off.

  • overwrite (bool, optional) – Toggles overwriting contents of dst.