unox.plot_format
================

.. py:module:: unox.plot_format


Functions
---------

.. autoapisummary::

   unox.plot_format.set_fig_row_col
   unox.plot_format.pad_extent
   unox.plot_format.get_var_label_and_units
   unox.plot_format.make_stage_comp_arrs
   unox.plot_format.format_sci_notation


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

.. py:function:: set_fig_row_col(n_subplots, n_rows=None, n_cols=None, **kwargs)

   Set the number of rows and columns in a figure.

   Determine the number of rows and columns in a figure based on the number of subplots.

   :param n_subplots: The total number of subplots in the figure.
   :type n_subplots: `int`
   :param n_rows: The number of rows to use in the figure. Default is `None`.
   :type n_rows: `int`, `None`, optional
   :param n_cols: The number of columns to use in the figure. Default is `None`.
   :type n_cols: `int`, `None`, optional
   :param \*\*kwargs: Additional keyword arguments accepted to facilitate wrapper functions.
   :type \*\*kwargs: keyword arguments

   :returns: * **n_rows** (`int`) -- The number of rows in the figure.
             * **n_cols** (`int`) -- The number of columns in the figure.

   .. rubric:: Examples

   >>> n_rows, n_cols = set_fig_row_col(4)
   2, 2
   >>> n_rows, n_cols = set_fig_row_col(6)
   2, 3
   >>> n_rows, n_cols = set_fig_row_col(6, n_rows=3)
   3, 2


.. py:function:: pad_extent(extent, padding=0.1)

   Pad the given extent.

   Pad the latitude and longitude extent of a dataset by enlarging the extent by the padding value.

   :param extent: A tuple of np.float64 in the form (lat_min, lat_max, lon_min, lon_max).
   :type extent: `tuple`
   :param padding: The amount to pad the extent by in a fraction.
   :type padding: `float`, optional

   :returns: **padded_extent** -- A tuple of np.float64 in the form (p_lat_min, p_lat_max, p_lon_min, p_lon_max).
   :rtype: `tuple`

   .. rubric:: Examples

   >>> nox = xr.open_dataset('datafiles/nox_2019_t106_US.nc')
   >>> extent = unox.data.get_extent(nox)
   >>> padded_extent = pad_extent(extent, padding=0.1)
   (20.635399999999997, 62.3546, -132.6375, -52.9875)


.. py:function:: get_var_label_and_units(var)

   Get the label and units for a variable.

   Return the label and units for a variable based on its name.

   :param var: The name of the variable.
   :type var: `str`

   :returns: * **label** (`str`) -- The label for the variable.
             * **units** (`str`) -- The units for the variable.

   .. rubric:: Examples

   >>> label, units = get_var_label_and_units('temperature')
   ('Temperature', '°C')


.. py:function:: make_stage_comp_arrs(in_arrs, this_date, var, avg_over=None, stage1_only=False)

   Create arrays for stage comparison plots.

   Create a dictionary of arrays for stage comparison, where each key is a stage and the value is an array of the variable for that stage.
   For use with the `unox.plotting.plot_stage_comp_maps()` function.

   :param in_arrs: A dictionary of input arrays, where the keys are stage names and the values are arrays.
                   Expects format like: {'truth': truth_arr, 'stage1': stage1_arr, 'stage2': stage2_arr}
   :type in_arrs: `dict`
   :param this_date: Date and time to select from the data file.
                     Expected format is 'YYYY-MM-DDTHH:MM:SS' or 'YYYY-MM-DD'.
   :type this_date: `np.datetime64` or `str`
   :param var: The variable which will be plotted.
   :type var: `str`
   :param avg_over: If provided, averages the data over the specified time period.
                    If None, takes just the time slice specified in `datetime`.
   :type avg_over: `str`, `numpy.timedelta64`, `None`, optional
   :param stage1_only: If True, produce arrays just corresponding to stage 1. If False, produce arrays
                       for stage 1 and stage 2. Default is False.
   :type stage1_only: `bool`, optional

   :returns: * **out_arrs** (`dict`) -- A dictionary of output arrays for each stage.
             * **overall_title** (`str`) -- A title for the overall plot, based on the variable and date(s).

   .. rubric:: Examples

   >>> # Example usage
   >>> out_arrs, title = make_stage_comp_arrs(in_arrs, '2019-01-01', 'no2')


.. py:function:: format_sci_notation(x, ndp=2, sci_lims_f=(-3, 3), pm_val=None, condense=False)

   Format a number into scientific notation.

   Return a formatted string of a number in scientific notation if the exponent is outside the specified limits.
   Uses LaTeX formatting for the string to be used in plot labels.

   :param x: The number to format.
   :type x: `float`, `int`
   :param ndp: The number of decimal places to include in the formatted string.
               Default is 2.
   :type ndp: `int`, optional
   :param sci_lims_f: The limits on the powers of 10 between which scientific notation will not be used.
                      Default is (-3, 3).
   :type sci_lims_f: `tuple` of `int`, optional
   :param pm_val: The plus-minus uncertainty value to include in the formatted string after a `\pm` symbol.
                  If `None`, no uncertainty will be included.
                  Default is `None`.
   :type pm_val: `float`, `int`, `None`, optional
   :param condense: Whether to remove spaces around `\pm` and ` imes` operators in the formatted string.
                    Default is `False`.
   :type condense: `bool`, optional

   :returns: **formatted_str** -- The formatted string of the number in scientific notation if the exponent is outside the specified limits, or in normal decimal notation otherwise. If `pm_val` is provided, the uncertainty will be included in the formatted string.
   :rtype: `str`

   .. rubric:: Examples

   >>> format_sci_notation(0.00012345)
   '1.23\times10^{-4}'
   >>> format_sci_notation(12345, ndp=3)
   '1.234\times10^{4}'
   >>> format_sci_notation(0.00012345, sci_lims_f=(-5, 5))
   '0.00'
   >>> format_sci_notation(12345, sci_lims_f=(-5, 5))
   '12345.00'