scripts.plotting.regional_map_multicase
=======================================

.. py:module:: scripts.plotting.regional_map_multicase

.. autoapi-nested-parse::

   Module: regional_map_multicase

   Provides a plot with regional maps of specified variables for all cases (up to 10) in a row.

   Since this is a specialty plot, it looks for several custom options to be provided in the YAML configuration file. For example, one might include this block in the YAML:

   region_multicase:
       region_spec: [slat, nlat, wlon, elon]
       region_time_option: <calendar | zeroanchor>  If calendar, will look for specified years. If zeroanchor will use a nyears starting from year_offset from the beginning of timeseries
       region_start_year:
       region_end_year:
       region_nyear:
       region_year_offset:
       region_month: <NULL means look for season>
       region_season: <NULL means use annual mean>
       region_variables: <list of variables to try to use; allows for a subset of the total diag variables>



Functions
---------

.. autoapisummary::

   scripts.plotting.regional_map_multicase.my_formatwarning
   scripts.plotting.regional_map_multicase.regional_map_multicase
   scripts.plotting.regional_map_multicase._retrieve
   scripts.plotting.regional_map_multicase._get_month_number
   scripts.plotting.regional_map_multicase._get_sampling_string
   scripts.plotting.regional_map_multicase.regional_map_multicase_plot
   scripts.plotting.regional_map_multicase._get_plot_location
   scripts.plotting.regional_map_multicase._construct_outfile_name
   scripts.plotting.regional_map_multicase.autoscale_title
   scripts.plotting.regional_map_multicase.simple_case_shortener


Module Contents
---------------

.. py:function:: my_formatwarning(msg, *args, **kwargs)

.. py:function:: regional_map_multicase(adfobj)

   regional_map_multicase
   input -> ADF object

   Sketch of workflow:
   - check for regional options (see module docstring),
   - get case names/locations (time series are used),
   - determine plot location and type
   - detect per-variable plot options
   - Loop through variables: make one multi-panel plot per variable


.. py:function:: _retrieve(ropt, variable, casename, location, return_dataset=False)

   Custom function that retrieves a variable.
      Returns the variable as a DataArray, unless keyword return_dataset=True.

   Applies the regional and time interval selections based in values in ropt.

   ropt -> dict, regional options specified via YAML

   variable -> str, the variable to get from files

   casename -> str, case name for constructing file search

   location -> Path, path to case

   kwarg:
   return_dataset -> bool, if true, return the dataset object, otherwise return the DataArray
                     with `variable`


.. py:function:: _get_month_number(m)

   Utility to get the number (1-12) from a string form.

   Input, `m`, can be string or integer.
   If it is a string, can be 3-letter abbreviation or full month name.
   If integer, needs to be 1-12.
   Emits a useful string if it looks like a season abbreviation.


.. py:function:: _get_sampling_string(ropt)

   Determines a string to use for the output file.
   The month that is specified as `region_month`,
   the season specified as `region_season`,
   or `ANN` otherwise,
   in that order of precedence.

   Note: if month is specified as an integer, that is what will be returned.


.. py:function:: regional_map_multicase_plot(adf, datadict, opt=None)

   Make a figure with up to 10 cases in a row of maps for specified region.


.. py:function:: _get_plot_location(adfobj)

   Determine plot location based on ADF object.
   Create location if it is not a directory.
   Return a Path object to the directory.


.. py:function:: _construct_outfile_name(ploc, ptype, *args)

   Construct a complete Path object for the output plot.
   ploc -> plot location directory (expects Path object)
   ptype -> file extension for output (e.g., pdf, png)
   args -> arbitrary arguments to be joined by underscores

   Example:
   _construct_outfile_name("/scratch/plots", "png", "cam6.120", "PRECT", "March", "LabSea")
   [returns] /scratch/plots/cam6.120_PRECT_March_LabSea_MultiCaseRegion_Mean.png


.. py:function:: autoscale_title(tiobj, ax, fig)

   Utility function that tries to shrink the title to fit on top of the Axes.


.. py:function:: simple_case_shortener(case_names)

   Reduce case names by removing a common prefix.
   Short case names would be better!