scripts.plotting.global_latlon_map
==================================

.. py:module:: scripts.plotting.global_latlon_map

.. autoapi-nested-parse::

   Generate global maps of 2-D fields

   Functions
   ---------
   global_latlon_map(adfobj)
       use ADF object to make maps
   my_formatwarning(msg, *args, **kwargs)
       format warning messages
       (private method)
   plot_file_op
       Check on status of output plot file.



Functions
---------

.. autoapisummary::

   scripts.plotting.global_latlon_map.my_formatwarning
   scripts.plotting.global_latlon_map.global_latlon_map
   scripts.plotting.global_latlon_map.plot_file_op
   scripts.plotting.global_latlon_map.aod_latlon
   scripts.plotting.global_latlon_map.monthly_to_seasonal
   scripts.plotting.global_latlon_map.aod_panel_latlon
   scripts.plotting.global_latlon_map.regrid_to_obs


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

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

   Issue `msg` as warning.


.. py:function:: global_latlon_map(adfobj)

   This script/function is designed to generate global
   2-D lat/lon maps of model fields with continental overlays.

   :param adfobj: The diagnostics object that contains all the configuration information
   :type adfobj: AdfDiag

   :rtype: Does not return a value; produces plots and saves files.

   .. rubric:: Notes

   It uses the AdfDiag object's methods to get necessary information.
   Makes use of AdfDiag's data sub-class.
   Explicitly accesses:
   adfobj.diag_var_list
       List of variables
   adfobj.plot_location
       output plot path
   adfobj.climo_yrs
       start and end climo years of the case(s), `syears` & `eyears`
       start and end climo years of the reference, `syear_baseline` & `eyear_baseline`
   adfobj.variable_defaults
       dict of variable-specific plot preferences
   adfobj.read_config_var
       dict of basic info, `diag_basic_info`
       Then use to check `plot_type`
   adfobj.debug_log
       Issues debug message
   adfobj.add_website_data
       Communicates information to the website generator
   adfobj.compare_obs
       Logical to determine if comparing to observations

   The `plotting_functions` module is needed for:
   pf.get_central_longitude()
       determine central longitude for global plots
   pf.lat_lon_validate_dims()
       makes sure latitude and longitude are valid
   pf.seasonal_mean()
       calculate seasonal mean
   pf.plot_map_and_save()
       send information to make the plot and save the file
   pf.zm_validate_dims()
       Checks on pressure level dimension


.. py:function:: plot_file_op(adfobj, plot_name, var, case_name, season, web_category, redo_plot, plot_type)

   Check if output plot needs to be made or remade.

   :param adfobj: The diagnostics object that contains all the configuration information
   :type adfobj: AdfDiag
   :param plot_name: path of the output plot
   :type plot_name: Path
   :param var: name of variable
   :type var: str
   :param case_name: case name
   :type case_name: str
   :param season: season being plotted
   :type season: str
   :param web_category: the category for this variable
   :type web_category: str
   :param redo_plot: whether to overwrite existing plot with this file name
   :type redo_plot: bool
   :param plot_type: the file type for the output plot
   :type plot_type: str

   :returns: Returns 1 if existing file is removed or no existing file.
             Returns None if file exists and redo_plot is False
   :rtype: int, None

   .. rubric:: Notes

   The long list of parameters is because add_website_data is called
   when the file exists and will not be overwritten.


.. py:function:: aod_latlon(adfobj)

   Function to gather data and plot parameters to plot a panel plot of model vs observation
     difference and percent difference.

   Calculate the seasonal means for DJF, MAM, JJA, SON for model and obs datasets

   NOTE: The model lat/lons must be on the same grid as the observations. If they are not, they will be
         regridded to match both the MERRA and MODIS observation dataset using helper function 'regrid_to_obs'

         For details about spatial coordiantes of obs datasets, see /glade/campaign/cgd/amp/amwg/ADF_obs/:
           - MERRA2_192x288_AOD_2001-2020_climo.nc
           - MOD08_M3_192x288_AOD_2001-2020_climo.nc


.. py:function:: monthly_to_seasonal(ds, obs=False)

.. py:function:: aod_panel_latlon(adfobj, plot_titles, plot_params, data, season, obs_name, case_name, case_num, types, symmetric=False)

   Function to plot a panel plot of model vs observation difference and percent difference

   This will be a 4-panel plot if model vs model run:
       - Top left is test model minus obs
       - Top right is baseline model minus obs
       - Bottom left is test model minus obs percent difference
       - Bottom right is baseline model minus obs percent difference

   This will be a 2-panel plot if model vs obs run:
       - Top is test model minus obs
       - Bottom is test model minus obs percent difference

   NOTE: Individual plots of the panel plots will be created and saved to plotting location(s)
         but will not be published to the webpage (if enabled)


.. py:function:: regrid_to_obs(adfobj, model_arr, obs_arr)

   Check if the model grid needs to be interpolated to the obs grid. If so,
   use xesmf to regrid and return new dataset