arctichoke.plot.labels_and_titles
=================================

.. py:module:: arctichoke.plot.labels_and_titles


Functions
---------

.. autoapisummary::

   arctichoke.plot.labels_and_titles.make_title
   arctichoke.plot.labels_and_titles.make_label


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

.. py:function:: make_title(dataset: (str, [str], xarray.Dataset), add_source_id: bool = True, add_experiment_id: bool = True, add_variant_label: bool = True, add_time_stamp: bool = True, **kwargs)

   Create a title for the dataset for use in plots.

   Assemble a title to be used in plots for this dataset based on the specified attributes.

   :param dataset: The dataset for which to make a title.
   :type dataset: `str`, list of `str`, `xarray.Dataset`
   :param add_source_id: Whether to add the source ID to the title.
                         Default is `True`.
   :type add_source_id: `bool`, optional
   :param add_experiment_id: Whether to add the eperiment ID to the title.
                             Default is `True`.
   :type add_experiment_id: `bool`, optional
   :param add_variant_label: Whether to add the variant label to the title.
                             Default is `True`.
   :type add_variant_label: `bool`, optional
   :param add_time_stamp: Whether to add the time stamp to the title.
                          This is only done if the given dataset only has one time value.
                          Default is `True`.
   :type add_time_stamp: `bool`, optional

   :returns: **dataset_title** -- The title for the dataset.
   :rtype: `str`

   .. rubric:: Examples

   >>> from arctichoke.plot.labes_and_titles import make_title
   >>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
   >>> make_title(example_file)
   'EC-Earth3P-HR hist-1950 r1i1p1f1 '
   >>> import xarray as xr
   >>> example_xr = xr.open_dataset(example_file).isel(time=6)
   >>> make_title(example_xr)
   'EC-Earth3P-HR hist-1950 r1i1p1f1 2000-07-16T12:00:00.000000000 '


.. py:function:: make_label(dataset: (str, [str], xarray.DataArray, xarray.Dataset), var: str = None, add_name: bool = True, add_units: bool = True, **kwargs)

   Create a label for the specified variable in the given dataset for use in plots.

   Assemble a label to be used in plots on axes or colorbars for the specified variable in the given dataset based on the specified attributes.

   :param dataset: The dataset for which to make a label.
   :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset`
   :param var: The variable in `dataset` for which to make a label.
               This is required if `dataset` is an `xarray.Dataset`.
               Default is `None`.
   :type var: `str`, `None`, optional
   :param add_name: Whether to add the variable name to the label.
                    Default is `True`.
   :type add_name: `bool`, optional
   :param add_units: Whether to add the units to the label.
                     Default is `True`.
   :type add_units: `bool`, optional

   :returns: **dataset_label** -- The label for the dataset.
   :rtype: `str`

   .. rubric:: Examples

   >>> from arctichoke.plot.labes_and_titles import make_label
   >>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
   >>> make_label(example_file, 'siconc')
   'Sea Ice Area Fraction (Ocean Grid) (%) '