plotcase.py =========== Purpose ------- ``plotcase.py`` is a visualization tool for CIME case outputs from ELM/CLM simulations. It reads model history files, performs temporal averaging, and generates time series plots comparing model output with optional observational data. The script can output both graphical plots (PDF/PNG) and NetCDF files containing the processed data. Command-line Arguments ---------------------- Case and Run Specification ~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``--csmdir `` Base CESM/E3SM directory containing case run directories (default: ``..``) ``--runnames `` Comma-delimited list of full case names. Overrides ``--cases``, ``--sites``, and ``--compset`` ``--cases `` Comma-delimited list of case ID prefixes to plot ``--compset `` Compset to plot (default: ``I20TRCLM45CN``) ``--titles `` Comma-delimited list of titles for legend entries. If not specified, uses runnames ``--sites `` Site code(s) to plot (default: ``none``) ``--model_name `` Model name in model output NetCDF files (default: ``elm``) Variable Selection ~~~~~~~~~~~~~~~~~~ ``--varfile `` File containing list of variables to plot, one per line (default: ``varfile``) ``--vars `` Comma-delimited list of variables to plot. Overrides ``--varfile`` and sends plot to screen instead of file ``--index `` Index (site or PFT) to extract from output arrays (default: 0). Use negative value to average over all sites/PFTs Temporal Selection and Averaging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``--ystart `` Beginning model year to plot (default: 1) ``--yend `` Final model year to plot (default: 9999) ``--ystart_obs `` Beginning year for observations (default: 0) ``--yend_obs `` Final year for observations (default: 0) ``--avpd `` Averaging period in number of output timesteps (default: 1) ``--timezone `` Time zone offset relative to UTC (default: 0) ``--hist_mfilt `` Override hist_mfilt value from lnd_in (default: -999, read from lnd_in) ``--hist_nhtfrq `` Override hist_nhtfrq value from lnd_in (default: -999, read from lnd_in) History File Selection ~~~~~~~~~~~~~~~~~~~~~~ ``--h1`` Use h1 history files (default: h0) ``--h2`` Use h2 history files (default: h0) ``--h3`` Use h3 history files (default: h0) ``--h4`` Use h4 history files (default: h0) Plot Types Supported -------------------- Default Time Series ~~~~~~~~~~~~~~~~~~~ Default behavior generates time series plots of variables over the specified year range. The script automatically detects output frequency (monthly, daily, hourly, annual) from the lnd_in namelist or history file configuration. Diurnal Cycle ~~~~~~~~~~~~~ ``--diurnal`` Plot diurnal (24-hour) cycle average ``--dstart `` Beginning day-of-year for diurnal average (default: 1) ``--dend `` Final day-of-year for diurnal average (default: 365) Requires hourly output. Averages all days within the specified DOY range across all years. Seasonal Cycle ~~~~~~~~~~~~~~ ``--seasonal`` Plot seasonal (12-month) cycle average Averages each calendar month across all years in the specified range. Spinup Cases ~~~~~~~~~~~~ ``--spinup`` Plot accelerated decomposition (AD) spinup and final spinup together ``--ad_Pinit`` AD spinup case initialized with P pools (CN mode) but other cases use CNP mode Plot Configuration ~~~~~~~~~~~~~~~~~~ ``--scale_factor `` Multiply all values by this factor (default: -999, auto-detect). Auto-detection converts gC/m^2/s to g.C/m2/day and mm/s to mm/day ``--ylog`` Use logarithmic scale for Y axis ``--nperpage `` Number of plots per page/figure (default: 1) Observations ~~~~~~~~~~~~ ``--obs`` Plot observations alongside model output. Reads FluxNet-format CSV files from a hardcoded directory (``/home/ac.ricciuto/fluxnet``) Supported observational variables: - ``NEE`` (NEE_CUT_REF) - ``GPP`` / ``FPSN`` (GPP_NT_CUT_REF) - ``ER`` (RECO_NT_CUT_REF) - ``EFLX_LH_TOT`` (LE_F_MDS) - ``FSH`` (H_F_MDS) - ``TBOT`` (TA_F_MDS) - ``FSDS`` (SWIN_F_MDS) - ``WIND`` (WS_F) - ``RAIN`` (P_F) Includes uncertainty bars when available. Output Formats -------------- Graphics ~~~~~~~~ ``--pdf`` Save plots to PDF files ``--png`` Save plots to PNG files ``--noplot`` Disable plot generation (only create NetCDF output) If neither ``--pdf`` nor ``--png`` is specified and ``--vars`` is used, plots are displayed interactively on screen. ``--outputdir `` Location for plots directory (default: ``//plots/``) NetCDF Output ~~~~~~~~~~~~~ The script always generates two NetCDF files in the output directory: ``___model.nc`` Contains processed model output ``___obs.nc`` Contains processed observational data (if available) NetCDF files include: - Time dimension and coordinate variable (days since start year, noleap calendar) - Gridcell dimension (one per case plotted) - Site name, latitude, longitude for each gridcell - All requested variables with proper units and missing value handling - Variables converted to CF-compliant units (e.g., gC/m^2/s → kg.C/m2/s) File Structure ~~~~~~~~~~~~~~ Files are organized as:: / ___model.nc ___obs.nc .pdf (if --nperpage=1) figure1.pdf (if --nperpage>1) figure2.pdf ... Special Variable Handling ------------------------- ``RAIN`` Automatically adds ``SNOW`` variable to compute total precipitation Statistics ---------- When observations are available, the script computes and uses: - RMSE (Root Mean Square Error) - Bias (mean difference) - Correlation coefficient These are calculated internally but not currently written to output files. Notes ----- - The script expects CIME case structure: ``//run/`` containing history files - History file naming follows CIME convention: ``..h..nc`` - The ``lnd_in`` namelist file must exist in the run directory to determine output configuration - Multiple cases can be plotted together for comparison - The ``--runnames`` option provides full control over case naming when the standard prefix+site+compset pattern doesn't apply - Special handling for ``RAIN`` variable: automatically sums ``RAIN`` and ``SNOW`` for total precipitation