arctichoke.dataset.trim_dataset
===============================

.. py:module:: arctichoke.dataset.trim_dataset


Attributes
----------

.. autoapisummary::

   arctichoke.dataset.trim_dataset.cdo
   arctichoke.dataset.trim_dataset.cdo


Functions
---------

.. autoapisummary::

   arctichoke.dataset.trim_dataset.trim_latlon
   arctichoke.dataset.trim_dataset.trim_files


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

.. py:data:: cdo

.. py:data:: cdo

.. py:function:: trim_latlon(dataset: (str, xarray.Dataset, xarray.DataArray), map_bbox: [float, float, float, float] = sps.NWP_BBOX, precise_trim: bool = False, save_as: str = None, verbose: bool = False)

   Trim the given dataset.

   Select only the data within the given bounding box of latitude and longitude coordinates from the given dataset.

   :param dataset: The dataset to plot.
   :type dataset: `str`, `xarray.Dataset`, `xarray.DataArray`
   :param map_bbox:
                    An array of coordinates defining the bounding box of the map in the following format:
                        - [LAT_MAX, LAT_MIN, LON_MAX, LON_MIN]

                    Default is `arctichoke.params.latlon_params.NWP_BBOX`.
   :type map_bbox: Array of `float`, optional
   :param precise_trim: Whether to precisely trim an irregular grid to the bounding box, making all values outside the bounding box null.
                        Default is `False`.
   :type precise_trim: `bool`, optional
   :param save_as: The file name to which to save the modified dataset.
                   Default is `None`, which doesn't save the dataset to a file.
   :type save_as: `str`, `None`, optional
   :param verbose: Whether to verbosely output information as the function executes.
                   Default is `False`.
   :type verbose: `bool`, optional

   :returns: **xr_data_trimmed** -- The dataset trimmed to the latitude and longitude ranges provided.
   :rtype: `xarray.Dataset`

   .. rubric:: Examples

   >>>


.. py:function:: trim_files(files_to_trim: [str], name_prefix: str = 'trim_', use_cdo_python: bool = True, overwrite: bool = False, **kwargs)

   Trim the specified files and save them as new files.

   For each given file, load the data, trim the dataset, then save that trimmed dataset as a new file in the same location with a new filename.

   :param files_to_trim: A list of paths of the data files to trim.
   :type files_to_trim: List of `str`
   :param name_prefix: The prefix to be prepended to each file name when saving.
                       Default is `trim_`.
   :type name_prefix: `str`, optional
   :param use_cdo_python: Whether to tell `trim_latlon()` to use the Python implementation of `cdo` or use `subprocess` to run a shell command.
                          Default is `True` which uses the Python implementation of `cdo`.
   :type use_cdo_python: `bool`, optional
   :param overwrite: Whether to overwrite an existing file if it exists.
                     Default is `False`.
   :type overwrite: `bool`, optional
   :param \*\*kwargs: Keyword arguments to pass to `trim_latlon()`.

   :rtype: None

   .. rubric:: Examples

   >>> from arctichoke.path.find_data import list_variable_files
   >>> list_of_files = list_variable_files('EC-Earth3P-HR', 'siage', variant_label='r3i1p2f1')
   >>> from arctichoke.dataset.trim_dataset import trim_files
   >>> trim_files(list_of_files)
   (trim_files) `name_prefix`: trim_NWP_
   (trim_latlon) `save_as`: /arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siage/gn/v20190214/trim_NWP_siage_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_195001-195012.nc
   ...
   (trim_latlon) `save_as`: /arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siage/gn/v20190214/trim_NWP_siage_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201401-201412.nc