Visualizing KPP-Standalone box model output

This page describes how you can plot results from the KPP-Standalone box model with GCPy.

Creating plots from KPP-Standalone output

Quick-look plots

You can use GCPy module gcpy/kpp/kppsa_quick_look.py to generate a vertical profile for a given species at a given observation site. This can be useful as a quick-look sanity check.

First, activate your Python virtual environment

$ mamba activate gcpy_env   # If using Mamba, or

$ conda activate gcpy_env   # If using Conda

Then run the kppsa_quick_look.py module from the command line:

(gcpy_env) $ python -m gcpy.kpp.kppsa_quick_look \
 --dirname /path/to/KPP-Standalone/output        \
 --label   Rosenbrock                            \
 --pattern Beijing*20190701_0040.log             \
 --species O3

This will create the following plot:

Vertical profiles at multiple observation sites

You can use GCPy module gcpy/kpp/kppsa_plot_sites.py to generate vertical profile plots for a given species at multiple observation locations.

First, activate your Python virtual environment

$ mamba activate gcpy_env   # If using Mamba, or

$ conda activate gcpy_env   # If using Conda

Then run the kppsa_plot_sites.py module from the command line:

(gcpy_env) $ python -m gcpy.kpp.kppsa_plot_sites  \
 --refdir   /path/to/KPP-Standalone/Ref/log/files \
 --reflabel Rosenbrock                            \
 --devdir   /path/to/KPP-Standalone/Dev/log/files \
 --devlabel Backwards Euler                       \
 --pattern  20190701_0040.log                     \
 --species  O3                                    \
 --pdfname  KPP-Standalone-O3-20190701-0040.pdf

This will create a PDF file with several pages. Each page will look similar to this:

In some instances (such as in the plot above), the Dev simulation (blue line) will overlap the Ref simulation (red line). This indicates that Dev has produced identical or nearly-identical results to Ref.

Source code reference

List of functions

Functions for reading and plotting KPP-Standalone box model output
Function	In file	Description
kppsa_make_quick_look_plot	`kppsa_quick_look.py`	Creates a “quick-look” vertical profile plot. Useful as a sanity check.
kppsa_plot_species_at_sites	`kppsa_plot_sites.py`	Creates vertical profile plots of a given species at various locations.
kppsa_get_file_list	`kppsa_utils.py`	Returns a list of KPP-Standalone log files matching a search criteria.
kppsa_read_one_csv_file	`kppsa_utils.py`	Reads a single log file (in CSV format) from the KPP standalone box model into a pandas.DataFrame object.
kppsa_read_csv_files	`kppsa_utils.py`	Reads all KPP standalone log files for a given site in a given directory.
kppsa_prepare_site_data	`kppsa_utils.py`	Returns a pd.DataFrame object containing data for a given species, and observation site, as well as the corresponding top-of-plot title.
kppsa_plot_single_site	`kppsa_utils.py`	Plots observation data vs. model data at a single station site.
kppsa_plot_one_page	`kppsa_utils.py`	Plots a single page of models vs. observations.
kppsa_get_unique_site_names	`kppsa_utils.py`	Returns a list of unique sites where KPP-Standalone box model output has been archived.

Function `kppsa_make_quick_look_plot`

def kppsa_make_quick_look_plot(file_list, label, species):
    """
    Creates a quick-look plot from KPP-Standalone box model output.

    Args
    file_list : list : List of KPP-Standalone log files
    site_name : str  : Name of the site that you wish to plot
    label     : str  : Descriptive label for the data
    species   : str  : Name of the species that you wish to plot
    """

Function `kppsa_plot_species_at_sites`

def kppsa_plot_species_at_sites(
        ref_file_list,
        ref_label,
        dev_file_list,
        dev_label,
        species,
        pdfname,
):
    """
    Creates vertical profile plots of a given species
    from KPP-Standalone box model output.

    Args
    ref_file_list : list : KPP-Standalone log files for "Ref" version
    ref_label     : str  : Label for the "Ref" version
    dev_file_list : list : KPP-Standalone log files for "Dev" version
    dev_label     : str  : Label for the "Dev" version
    species       : str  : Name of the species to plot
    pdfname       : str  : Name of the output PDF file
    """

Function `kppsa_get_file_list`

def kppsa_get_file_list(
        input_dir,
        pattern=""
):
    """
    Returns a list of KPP-Standalone log files matching
    a search criteria.

    Args
    input_dir : str  : Directory with KPP-Standalone log files
    pattern   : str  : Read files matching this pattern (Default = "")

    Returns
    file_list : list : List of files matching the criteria
    """

Function `kppsa_read_one_csv_file`

def kppsa_read_one_csv_file(file_name):
    """
    Reads a single log file (in CSV format) from the KPP
    standalone box model into a pandas.DataFrame object.

    Args
    file_name : str          : File to be read

    Returns
    dframe    : pd.DataFrame : DataFrame with the results
    """

Function `kppsa_read_csv_files`

def kppsa_read_csv_files(file_list):
    """
    Reads all KPP standalone log files for a given site
    in a given directory.

    Args
    input_dir  : str          : Directory to search
    site       : str          : KPP standalone site name

    Returns
    dframe_all : pd.DataFrame : Observations at all levels
    """

Function `kppsa_prepare_site_data`

def kppsa_prepare_site_data(
        dframe,
        site_name,
        species,
):
    """
    Returns a pd.DataFrame object containing data for a given species,
    and observation site, as well as the corresponding top-of-plot
    title.  Species data is limited from the surface to 500 hPa.

    Args
    dframe     : pd.DataFrame : KPP-Standalone output data
    site_name  : str          : Name of site to plot
    species    : species      : Name of species to plot

    Returns
    site_data  : pd.DataFrame : Data for the given site & species
    site_title : str          : Corresponding plot title string
    """

Function `kppsa_plot_single_site`

def 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,
):
    """
    Plots observation data vs. model data at a single station site.

    Args:
    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
    ref_data       : pd.DataFrame      : Observations at each station site
    ref_label      : str               : Label for the Ref model data
    dev_data       : pd.DataFrame      :
    dev_label      : str               : Label for the Dev model data
    site_name      : str               : Name of the station site
    species        : pd.Series         : Data from the Ref model version
    font_scale     : float             : Scale fac to increase font size
    """

Function `kppsa_plot_one_page`

def 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,
):
    """
    Plots a single page of models vs. observations.

    Args:
    pdf             : pdf          : PDF object
    ref_dframe      : pd.DataFrame : Observations at each station site.
    ref_label       : str          : Label for the observational data
    dev_dframe      : pd.DataFrame : Data from the Ref model version
    dev_label       : str          : Label for the Ref model data
    species         : str          : Name of the species to plot
    dev_dataarray   : xr.DataArray : Data from the Dev model version
    dev_label       : str          : Label for the Dev model data
    dev_cs_grid     : str|None     : Metadata for Dev cubed-sphere grid
    gc_levels       : pd.DataFrame : Metadata for model vertical levels
    rows_per_page   : int          : Number of rows to plot on a page
    cols_per_page   : int          : Number of cols to plot on a page
    font_scale      : float        : PDF output file name
    """

Function `kppsa_get_unique_site_names`

def kppsa_get_unique_site_names(dframe):
    """
    Returns a list of unique sites where KPP-Standalone box model
    output has been archived.

    Args
    dframe     : pd.DataFrame : Object containing KPP-Standalone output

    Returns
    site_names : list of str  : List of unique site names
    """

Visualizing KPP-Standalone box model output

Creating plots from KPP-Standalone output

Quick-look plots

Vertical profiles at multiple observation sites

Source code reference

List of functions

Function kppsa_make_quick_look_plot

Function kppsa_plot_species_at_sites

Function kppsa_get_file_list

Function kppsa_read_one_csv_file

Function kppsa_read_csv_files

Function kppsa_prepare_site_data

Function kppsa_plot_single_site

Function kppsa_plot_one_page

Function kppsa_get_unique_site_names