{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Averaging over dimensions of the dataset\n",
    "\n",
    "The average over dimensions operation makes use of `clisops.core.average` to process the datasets and to set the output type and the output file names.\n",
    "\n",
    "It is possible to average over none or any number of time, longitude, latitude or level dimensions in the dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize the testing data\n",
    "import clisops.utils.testing as clite\n",
    "\n",
    "Stratus = clite.stratus(\n",
    "    repo=clite.XCLIM_TEST_DATA_REPO_URL, branch=clite.XCLIM_TEST_DATA_VERSION, cache_dir=clite.XCLIM_TEST_DATA_CACHE_DIR\n",
    ")\n",
    "\n",
    "# fetch files locally or from GitHub\n",
    "tas_files = [\n",
    "    Stratus.fetch(\"cmip5/tas_Amon_HadGEM2-ES_rcp85_r1i1p1_200512-203011.nc\"),\n",
    "    Stratus.fetch(\"cmip5/tas_Amon_HadGEM2-ES_rcp85_r1i1p1_203012-205511.nc\"),\n",
    "    Stratus.fetch(\"cmip5/tas_Amon_HadGEM2-ES_rcp85_r1i1p1_205512-208011.nc\"),\n",
    "]\n",
    "\n",
    "o3_file = Stratus.fetch(\"cmip6/o3_Amon_GFDL-ESM4_historical_r1i1p1f1_gr1_185001-194912.nc\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameters\n",
    "\n",
    "Parameters taken by the `average_over_dims` are below:\n",
    "\n",
    "    ds: Union[xr.Dataset, str]\n",
    "    dims : Optional[Union[Tuple[str], DimensionParameter]]\n",
    "      The dimensions over which to apply the average. If None, none of the dimensions are averaged over. Dimensions\n",
    "      must be one of [\"time\", \"level\", \"latitude\", \"longitude\"].\n",
    "    ignore_undetected_dims: bool\n",
    "      If the dimensions specified are not found in the dataset, an Exception will be raised if set to True.\n",
    "      If False, an exception will not be raised and the other dimensions will be averaged over. Default = False\n",
    "    output_dir: Optional[Union[str, Path]] = None\n",
    "    output_type: {\"netcdf\", \"nc\", \"zarr\", \"xarray\"}\n",
    "    split_method: {\"time:auto\"}\n",
    "    file_namer: {\"standard\", \"simple\"}\n",
    "\n",
    "\n",
    "The output is a list containing the outputs in the format selected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import xarray as xr\n",
    "\n",
    "from clisops.exceptions import InvalidParameterValue\n",
    "from clisops.ops.average import average_over_dims"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds = xr.open_mfdataset(tas_files, decode_times=xr.coders.CFDatetimeCoder(use_cftime=True), combine=\"by_coords\")\n",
    "\n",
    "ds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Average over one dimension"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = average_over_dims(ds, dims=[\"time\"], ignore_undetected_dims=False, output_type=\"xarray\")\n",
    "\n",
    "result[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see in the output dataset, time has been averaged over and has been removed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Average over two dimensions\n",
    "\n",
    "Averaging over two dimensions is just as simple as averaging over one. The dimensions to be averaged over should be passed in as a sequence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = average_over_dims(ds, dims=[\"time\", \"latitude\"], ignore_undetected_dims=False, output_type=\"xarray\")\n",
    "\n",
    "result[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case both the time and latitude dimensions have been removed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Allowed dimensions\n",
    "\n",
    "It is only possible to average over longtiude, latitude, level and time. If a different dimension is provided to average over an error will be raised."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    average_over_dims(\n",
    "        ds,\n",
    "        dims=[\"incorrect_dim\"],\n",
    "        ignore_undetected_dims=False,\n",
    "        output_type=\"xarray\",\n",
    "    )\n",
    "except InvalidParameterValue as exc:\n",
    "    print(exc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dimensions not found"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the case where a dimension has been selected for averaging but it doesn't exist in the dataset, there are 2 options.\n",
    "\n",
    "1. To raise an exception when the dimension doesn't exist, set `ignore_undetected_dims = False`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    average_over_dims(\n",
    "        ds,\n",
    "        dims=[\"level\", \"time\"],\n",
    "        ignore_undetected_dims=False,\n",
    "        output_type=\"xarray\",\n",
    "    )\n",
    "except InvalidParameterValue as exc:\n",
    "    print(exc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. To ignore when the dimension doesn't exist, and average over any other requested dimensions anyway, set `ignore_undetected_dims = True`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = average_over_dims(\n",
    "    ds,\n",
    "    dims=[\"level\", \"time\"],\n",
    "    ignore_undetected_dims=True,\n",
    "    output_type=\"xarray\",\n",
    ")\n",
    "result[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the case above, a level dimension did not exist, but this was ignored and time was averaged over anyway."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## No dimensions supplied"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If no dimensions are supplied, no averaging will be applied and the original dataset will be returned."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = average_over_dims(ds, dims=None, ignore_undetected_dims=False, output_type=\"xarray\")\n",
    "\n",
    "result[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## An example of averaging over level"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Original dataset\")\n",
    "print(xr.open_dataset(o3_file, decode_times=xr.coders.CFDatetimeCoder(use_cftime=True)))\n",
    "\n",
    "result = average_over_dims(\n",
    "    o3_file,\n",
    "    dims=[\"level\"],\n",
    "    ignore_undetected_dims=False,\n",
    "    output_type=\"xarray\",\n",
    ")\n",
    "\n",
    "\n",
    "print(\"Averaged dataset\")\n",
    "result[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above, the dimension `plev` has be removed and averaged over"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}