default_options.yaml

# This is the file containing default values for all options you can specify for the plotting
# script at runtime via YAML input.
# Details about the specific sections (groups of variables for a particular purpose) and
# individual variables can be found in the comments above each specific section/variable below.
#
# Some sections also include subsections with further settings related to a particular part of
# the plotting script; these are differentiated by the indentation level.
#
# Some variables must be specified in the plot_options.yaml file (the default values are invalid);
# these variables are labeled "(mandatory)".

# This section is for variables related to the specific data you want to plot
dataset:
  #
  # files (mandatory):
  # Full or relative path to filename containing MPAS data you wish to plot. Can be a single file,
  # a glob-able regex pattern match (e.g. /path/to/nc/data/*.nc), or a list of files
  #
  # gridfile:
  # Some MPAS files (usually "diag" files) do not contain grid information; in these cases you
  # must specify a "gridfile" that contains the grid information for the script to read. This can
  # be a static.nc file, init.nc file, or even a history file from the MPAS forecast
  # NOTE: Since only one gridfile can be specified, it is not possible to mix-and-match gridded
  #       and gridless files
  #
  filename: ''
  gridfile: ''

  # vars:
  # Dictionary of variables to plot. The key(s) of this dictionary should be the name of the
  # variables to plot, and the value for each key should be a dictionary of settings; for each
  # variable, source: is the only required variable. See config_plot.yaml.example for examples
  # of how this section can be filled in.

  # Note that for 'lev' you must provide a list of values, even if there is just one item in that
  # list. If no 'lev' is provided, all levels will be plotted. Some specific examples of how to
  # specify various combinations of variable and levels are provided below:

  # To plot the variable t2m at the 9th vertical level, use the following settings:
  #   vars:
  #     t2m:
  #       source: native
  #       lev:
  #         - 9
  #
  # To plot the variables qv and rho at all levels, use the following settings:
  #   vars:
  #     qv:
  #       source: native
  #     rho:
  #       source: native
  #
  # To plot the variable t2m at levels 1-6, and vorticity at all levels, use the following settings:
  #   vars:
  #     t2m:
  #       source: native
  #       lev:
  #         - 1
  #         - 2
  #         - 3
  #         - 4
  #         - 5
  #         - 6
  #     rho:
  #       source: native

  vars:

# This section is for variables related to how the plot(s) is/are created. Note that any settings
# here can be overridden on a per-variable basis above, by including a plot: section under any
# specific variable
plot:
  # filename:
  # The filename of the output plot(s). If an extension is included (e.g. ".png"), it will determine the format of the image.
  #
  # format:
  # The image format of the output, if not specified in the filename. See matplotlib documentation for valid options:
  # https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html#matplotlib.pyplot.savefig
  #
  # title:
  # Settings controlling the title of the output plot(s) that will appear in the image above the plotted data.
  #   text:
  #   The text of the title. To create a plot with no title, set "text" to a blank string.
  #   fontsize:
  #   The font size to use for the title.
  #
  # exists:
  # Handle case when file exists. Valid options are
  #    overwrite  Overwrite existing file
  #    abort      Raise an exception
  #    rename     Rename the old file using the scheme {filename}-#.png, where # is the next available sequential integer
  #
  # dpi:
  # Image dots per inch
  #
  # figheight:
  # Image height in inches
  #
  # figwidth:
  # Image width in inches

  # NOTE: for text fields such as filename, title, etc., some helpful variables are provided that
  # you can reference in the text string that will be substituted in the final output:
  # {var} = Variable name
  # {lev} = Variable level
  # {varln} = Variable "long name" (not recommended for filenames since these often contain spaces)
  # {units} = Variable units
  # {filename} = Name of file being read for plotted data
  # {fnme} = Name of file (minus extension) being read for plotted data
  # {date} = The date of plotted data, in %Y-%m-%d format
  # {time} = The time of plotted data, in %H:%M:%S format
  # {maxval} = The maximum value in the plotted data
  # {minval} = The minimum value in the plotted data

  filename: '{var}_{lev}.png'
  format: null
  title:
    text: 'Plot of {varln}, level {lev} for MPAS forecast, {date} {time}'
    fontsize: 8
  exists: rename
  dpi: 200
  figheight: 3
  figwidth: 6

  # colormap:
  # Color scheme to use for output plots. Options can either be standard Matplotlib colormaps (reference
  # https://matplotlib.org/stable/gallery/color/colormap_reference.html for valid options) or the name of
  # a custom colormap under the colormaps/ directory (currently just one option: "radar_refl").
  #
  # NOTE: custom colormaps also include additional settings that will overwrite user config choices; see
  # README.md for more information.
  #
  colormap: "viridis"

  # pixel_ratio:
  # This controls the quantity of pixels to sample in the rasterization process; higher numbers result
  # in higher quality plots, though at a cost of plotting speed.
  pixel_ratio: 1

  # polycollection:
  # NOT RECOMMENDED
  # This is the legacy plotting method that converts the unstructured grid to a set of polygons.
  # This can be orders of magnitude slower than the default raster method and so is not
  # recommended for large domains; if you need more detail in your plot, it's recommended to
  # increase the "pixel_ratio" setting.
  # periodic_bdy:
  # For periodic domains (including global), the polycollection routines will omit the boundary cells by default. To plot
  # all data, including boundaries, set this option to True, but note that it will slow down plotting substantially.
  #
  polycollection: False
  periodic_bdy: True # Set to false once UXarray issue is fixed! https://github.com/UXARRAY/uxarray/issues/1507

  # vmin, vmax:
  # By default the color range will be scaled to the max/min values of the plotted data. To use a custom range,
  # set vmin and/or vmax

  vmin: null
  vmax: null

  # plot_under, plot_over:
  # By default any values above vmax or below vmin will be plotted as the color for vmax/vmin respectively.
  # To omit these out-of-range values all together, set plot_over/plot_under to False respectively.

  plot_under: True
  plot_over: True

  # Settings for plotting grid cell borders. To disable cell borders, set color="face" (colors the border the same as cell face)
  # or set width=0
  edges:
    color: face
    width: 0.1

  # Settings for plotting political boundaries. Settings scale, color, linewidth can either be a single value (to apply to all boundaries)
  # or a list of values to apply to the specific level 0, 1, or 2 boundaries described below
  boundaries:
    enable: True
    # Level of political boundaries to plot. Level 0 is national boundaries, Level 1 is sub-national boundaries (e.g.
    # states, provinces, etc.), Level 2 is county boundaries (US only); counties require 10m scale
    detail: 0
    color: ['black','black','black']
    linewidth: [0.2,0.2,0.2]
    # Scale is the resolution of the plotted boundary dataset. Options are 110m, 50m, and 10m.
    scale: ['50m','50m','50m']

  # Settings for plotting coastlines.
  coastlines:
    enable: True
    # Scale is the resolution of the plotted boundary dataset. Options are 110m, 50m, and 10m.
    scale: '10m'
    color: 'black'
    linewidth: 0.5

  # Settings for plotting lakes.
  lakes:
    enable: False
    # Scale is the resolution of the plotted boundary dataset. Options are 110m, 50m, and 10m.
    scale: '50m'
    color: 'black'
    linewidth: 0.5

  # Settings for the plot's color bar
  colorbar:
    # orientation:
    # The orientation of the color bar. Valid values are "horizontal" or "vertical"
    #
    # label:
    # Text to tabel colorbar; can use variables described at start of "plot:" section
    #
    # fontsize:
    # Font size for the colobar label.
    enable: True
    orientation: vertical
    label: 'Units: {units}'
    fontsize: 8
    datalabels: null

  # Settings for the output map projection:
  projection:
    # Name of the actual projection; for valid options see https://scitools.org.uk/cartopy/docs/latest/reference/projections.html
    # A few special projections are not yet supported: UTM, OSGB, LambertZoneII, EuroPP, OSNI
    projection: PlateCarree
    # Range of latitudes/longitudes to plot. Each should be a 2-element list, with the first entry being less than the second
    latrange:
      - null
      - null
    lonrange:
      - null
      - null
    # Central lat/lon; needed to center the projection for some projections. If not supported, values will be ignored
    central_lat: null
    central_lon: null
    # Satellite height (meters): used for Geostationary and NearsidePerspective projections that simulate a satellite view
    satellite_height: null
    # Standard parallels: used for setting projection parameters for AlbersEqualArea, EquidistantConic, and LambertConformal
    standard_parallels:
      - null
      - null