gcpy.kpp.kppsa_utils

Utility functions for visualizing output from the KPP-Standalone box model.

Functions

kppsa_get_file_list(input_dir[, pattern])

Returns a list of KPP-Standalone log files matching a search pattern.

kppsa_get_unique_site_names(dframe)

Returns a list of unique observation site names from KPP-Standalone output, ordered from north to south.

kppsa_plot_one_page(pdf, site_names, ...[, ...])

Plots a single page of Ref vs.

kppsa_plot_single_site(fig, rows_per_page, ...)

Plots initial and final species concentrations as vertical profiles at a single observation site.

kppsa_prepare_site_data(dframe, site_name, ...)

Returns a DataFrame and plot title for a given species and observation site.

kppsa_read_csv_files(file_list)

Reads multiple KPP-Standalone log files and concatenates them into a single pandas DataFrame.

kppsa_read_one_csv_file(file_name)

Reads a single KPP-Standalone log file in CSV format into a pandas DataFrame.
gcpy.kpp.kppsa_utils.kppsa_get_file_list(input_dir, pattern='')[source]

Returns a list of KPP-Standalone log files matching a search pattern.

Parameters:

  • input_dir (str) – Directory containing KPP-Standalone log files.

  • pattern (str, optional) – Glob pattern used to filter filenames. All files containing this string will be returned. Default: "" (matches all files)

Returns:

file_list – List of file paths matching the search criteria.

Return type:

list of str

gcpy.kpp.kppsa_utils.kppsa_read_one_csv_file(file_name)[source]

Reads a single KPP-Standalone log file in CSV format into a pandas DataFrame.

Metadata fields (location, timestamp, longitude, latitude, vertical level, and pressure) are extracted from the file header and appended as additional columns.

Parameters:

file_name (str) – Path to the CSV-format KPP-Standalone log file to be read.

Returns:

dframe – DataFrame containing species concentrations and associated metadata extracted from the file header. Added columns are: Location, DateTime, Longitude, Latitude, Level, and Pressure.

Return type:

pandas.DataFrame

gcpy.kpp.kppsa_utils.kppsa_read_csv_files(file_list)[source]

Reads multiple KPP-Standalone log files and concatenates them into a single pandas DataFrame.

Parameters:

file_list (list of str) – Paths to KPP-Standalone CSV log files to be read.

Returns:

dframe_all – Concatenated DataFrame containing data from all files in file_list.

Return type:

pandas.DataFrame

gcpy.kpp.kppsa_utils.kppsa_prepare_site_data(dframe, site_name, species)[source]

Returns a DataFrame and plot title for a given species and observation site.

Data is filtered to include only observations at or below 500 hPa (surface to lower stratosphere) and sorted by descending pressure.

Parameters:

  • dframe (pandas.DataFrame) – KPP-Standalone output data as returned by kppsa_read_csv_files().

  • site_name (str) – Name of the observation site to extract data for.

  • species (str) – Name of the species to extract data for.

Returns:

  • site_data (pandas.DataFrame or None) – DataFrame filtered to the given site and species, sorted by descending pressure, and limited to pressures >= 500 hPa. Returns None if dframe is None.

  • site_title (str or None) – Plot title string including the site name, cardinal coordinates, and timestamp (e.g. "Mace Head (53°N,10°W) at 2019-07-01T00:00"). Returns None if dframe is None.

gcpy.kpp.kppsa_utils.kppsa_plot_single_site(fig, rows_per_page, cols_per_page, subplot_index, subplot_title, ref_data, ref_label, dev_data, dev_label, species, font_scale)[source]

Plots initial and final species concentrations as vertical profiles at a single observation site.

Parameters:

  • fig (matplotlib.figure.Figure) – Figure object into which the subplot will be added.

  • rows_per_page (int) – Number of subplot rows on the page.

  • cols_per_page (int) – Number of subplot columns on the page.

  • subplot_index (int) – Zero-based index of this subplot within the page grid.

  • subplot_title (str) – Title string displayed above this subplot.

  • ref_data (pandas.DataFrame) – KPP-Standalone output for the Ref model version at this site, as returned by kppsa_prepare_site_data().

  • ref_label (str) – Legend label for the Ref model final concentration.

  • dev_data (pandas.DataFrame or None) – KPP-Standalone output for the Dev model version at this site. Pass None to omit the Dev profile.

  • dev_label (str or None) – Legend label for the Dev model final concentration. Ignored if dev_data is None.

  • species (str) – Name of the species being plotted, used for axis labels and error checking.

  • font_scale (float) – Multiplicative scale factor applied to all font sizes, allowing text to be enlarged or reduced uniformly.

Raises:

  • ValueError – If species is not found in ref_data.

  • ValueError – If dev_data is not None and species is not found in dev_data.

Notes

The Y-axis (pressure) is plotted from 1020 hPa at the bottom to 500 hPa at the top. The Y-axis label is only applied to leftmost panels (subplot_index is 0 or a multiple of cols_per_page).

gcpy.kpp.kppsa_utils.kppsa_plot_one_page(pdf, site_names, ref_dframe, ref_label, dev_dframe, dev_label, species='O3', rows_per_page=3, cols_per_page=3, font_scale=1.0)[source]

Plots a single page of Ref vs. Dev vertical profiles for a list of observation sites and saves it to a PDF file.

Parameters:

  • pdf (matplotlib.backends.backend_pdf.PdfPages) – Open PDF file object to which the page will be saved.

  • site_names (list of str) – Names of the observation sites to plot on this page.

  • ref_dframe (pandas.DataFrame) – KPP-Standalone output for the Ref model version, as returned by kppsa_read_csv_files().

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

  • dev_dframe (pandas.DataFrame) – KPP-Standalone output for the Dev model version, as returned by kppsa_read_csv_files().

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

  • species (str, optional) – Name of the species to plot. Default: "O3"

  • rows_per_page (int, optional) – Number of subplot rows on the page. Default: 3

  • cols_per_page (int, optional) – Number of subplot columns on the page. Default: 3

  • font_scale (float, optional) – Multiplicative scale factor applied to all font sizes. Default: 1.0

Notes

The page is landscape-oriented (11” × 8”). A shared legend is placed at the top of the page. Vertical spacing between subplots is adjusted automatically.

gcpy.kpp.kppsa_utils.kppsa_get_unique_site_names(dframe)[source]

Returns a list of unique observation site names from KPP-Standalone output, ordered from north to south.

Parameters:

dframe (pandas.DataFrame) – KPP-Standalone output data as returned by kppsa_read_csv_files().

Returns:

unique_site_names – Unique site names sorted by descending latitude (north to south).

Return type:

list of str