#!/usr/bin/env python3
r"""
Script to visualize output from the KPP standalone box model.
Command-line Arguments
----------------------
.. option:: --refdir <str>
Folder containing KPP-Standalone output from the Ref model.
.. option:: [--reflabel <str>]
Plot label for the Ref model.
Default: ``"Ref"``
.. option:: --devdir <str>
Folder containing KPP-Standalone output from the Dev model.
.. option:: [--devlabel <str>]
Plot label for the Dev model.
Default: ``"Dev"``
.. option:: [--pattern <str>]
Glob pattern used to match KPP-Standalone log filenames.
.. option:: --species <str>
Name of the species to plot.
.. option:: [--pdfname <str>]
Name of the PDF file to be created.
Default: ``"kppsa_output.pdf"``
Raises
------
ValueError
If no Ref files matching ``--pattern`` are found in ``--refdir``.
ValueError
If no Dev files matching ``--pattern`` are found in ``--devdir``.
Example
-------
.. code-block:: console
$ conda activate gcpy_env
(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
"""
# Imports
import argparse
from matplotlib.backends.backend_pdf import PdfPages
import matplotlib.pyplot as plt
from gcpy.util import verify_variable_type
from gcpy.kpp.kppsa_utils import \
kppsa_get_file_list, kppsa_get_unique_site_names, \
kppsa_plot_one_page, kppsa_read_csv_files
[docs]
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.
Parameters
----------
ref_file_list : list of str
Paths to KPP-Standalone log files for the ``Ref`` version.
ref_label : str
Descriptive label for the ``Ref`` version, used in plot
titles and legends.
dev_file_list : list of str
Paths to KPP-Standalone log files for the ``Dev`` version.
dev_label : str
Descriptive label for the ``Dev`` version, used in plot
titles and legends.
species : str
Name of the species to plot.
pdfname : str
Path and name of the output PDF file. A ``.pdf`` extension
will be appended if not already present.
Notes
-----
Sites are sorted from north to south. Plots are arranged
``3 rows × 2 columns`` per page. The seaborn ``darkgrid`` style
is applied during plotting and reset to ``default`` afterwards
to avoid affecting other plotting scripts.
"""
verify_variable_type(ref_file_list, list)
verify_variable_type(ref_label, str)
verify_variable_type(dev_file_list, list)
verify_variable_type(dev_label, str)
verify_variable_type(species, str)
verify_variable_type(pdfname, str)
# Read data
ref_data = kppsa_read_csv_files(ref_file_list)
dev_data = kppsa_read_csv_files(dev_file_list)
# Get a list of site names sorted from N to S
site_names = kppsa_get_unique_site_names(ref_data)
# Figure setup
plt.style.use("seaborn-v0_8-darkgrid")
rows_per_page = 3
cols_per_page = 2
plots_per_page = rows_per_page * cols_per_page
# Open the plot as a PDF document
if ".pdf" not in pdfname:
pdfname += ".pdf"
pdf = PdfPages(f"{pdfname}")
# Loop over the number of obs sites that fit on a page
for start in range(0, len(site_names), plots_per_page):
end = start + plots_per_page - 1
kppsa_plot_one_page(
pdf,
site_names[start:end+1],
ref_data,
ref_label,
dev_data,
dev_label,
species,
rows_per_page,
cols_per_page,
font_scale=1.0,
)
# Close the PDF file
pdf.close()
# Reset the plot style (this prevents the seaborn style from
# being applied to other model vs. obs plotting scripts)
plt.style.use("default")
[docs]
def main():
"""
Parses command-line arguments and calls
:func:`kppsa_plot_species_at_sites`.
"""
# Tell the parser which arguments to look for
parser = argparse.ArgumentParser(
description="Single-panel plotting example program"
)
parser.add_argument(
"--refdir",
metavar="REFDIR",
type=str,
required=True,
help="Directory w/ KPP-Standalone log files (Ref version)"
)
parser.add_argument(
"--reflabel",
metavar="REFLABEL",
type=str,
required=False,
help="Descriptive label for the Ref data",
default="Ref"
)
parser.add_argument(
"--devdir",
metavar="DEVDIR",
type=str,
required=True,
help="Directory w/ KPP-Standalone log files (Dev version)"
)
parser.add_argument(
"--devlabel",
metavar="DEVLABEL",
type=str,
required=False,
help="Descriptive label for the Dev data",
default="Dev"
)
parser.add_argument(
"--pattern",
metavar="PATTERN",
type=str,
required=False,
help="Search for file names matching this pattern",
)
parser.add_argument(
"--species",
metavar="SPECIES",
type=str,
required=True,
help="Species to plot"
)
parser.add_argument(
"--pdfname",
metavar="PDF-FILE-NAME",
type=str,
required=False,
help="Name of the PDF file to be created",
default="kppsa_output.pdf"
)
# Parse command-line arguments
args = parser.parse_args()
# Get a list of KPP-Standalone files matching the criteria (Ref)
ref_file_list = kppsa_get_file_list(
args.refdir,
args.pattern,
)
if len(ref_file_list) == 0:
msg = "Could not find any files matching {pattern} for Ref!"
raise ValueError(msg)
dev_file_list = kppsa_get_file_list(
args.devdir,
args.pattern,
)
if len(dev_file_list) == 0:
msg = "Could not find any files matching {pattern} for Dev!"
raise ValueError(msg)
# Plot data
kppsa_plot_species_at_sites(
ref_file_list,
args.reflabel,
dev_file_list,
args.devlabel,
args.species,
args.pdfname,
)
if __name__ == '__main__':
main()