{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b5dbd013-e1bb-47bf-906c-1806092a9eb7",
   "metadata": {},
   "source": [
    "# Accessors"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50eb9058-05ec-496f-951b-e15e75668daa",
   "metadata": {},
   "source": [
    "To extend `xarray.DataArray` and  `xarray.Dataset`\n",
    "xradar aims to provide accessors which downstream libraries can hook into.\n",
    "\n",
    "Those accessors are yet to be defined. For starters we could implement purpose-based\n",
    "accessors (like `.vis`, `.kdp` or `.trafo`) on `xarray.DataArray` level.\n",
    "\n",
    "To not have to import downstream packages a similar approach to xarray.backends using\n",
    "`importlib.metadata.entry_points` could be facilitated.\n",
    "\n",
    "In this notebook the creation of such an accessor is showcased."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "514e9883-ca69-47b2-bced-35611c704342",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import xarray as xr\n",
    "import xradar as xd\n",
    "from open_radar_data import DATASETS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aaddab67-6a24-4dbf-8646-b260a76983fc",
   "metadata": {},
   "source": [
    "## Import Data\n",
    "\n",
    "Fetch data from [open-radar-data](https://github.com/openradar/open-radar-data) repository."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb75b7c5-9522-4029-849f-bcc702ad555a",
   "metadata": {},
   "outputs": [],
   "source": [
    "filename = DATASETS.fetch(\"71_20181220_060628.pvol.h5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ed04dfa-eccc-4ca6-8864-25ce467518e2",
   "metadata": {},
   "source": [
    "### Open data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "780c1f2f-db6b-4ea6-85d5-1066d01511cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "ds = xr.open_dataset(filename, group=\"sweep_0\", engine=\"odim\")\n",
    "display(ds.DBZH.values)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f042c04-7355-4774-97f3-beb86c77d5fe",
   "metadata": {},
   "source": [
    "### Plot DBZH"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a60e5fa1-8f31-46e2-a497-4477b4513485",
   "metadata": {},
   "outputs": [],
   "source": [
    "ds.DBZH.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5989665a-f33d-4403-9635-a786701978bb",
   "metadata": {},
   "source": [
    "## Define two example functions\n",
    "\n",
    "Functions copied verbatim from wradlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86f082bc-82e9-4cf6-9919-f3455cb1ee80",
   "metadata": {},
   "outputs": [],
   "source": [
    "def _decibel(x):\n",
    "    \"\"\"Calculates the decibel representation of the input values\n",
    "\n",
    "    :math:`dBZ=10 \\\\cdot \\\\log_{10} z`\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    x : float or :class:`numpy:numpy.ndarray`\n",
    "        (must not be <= 0.)\n",
    "\n",
    "    Examples\n",
    "    --------\n",
    "    >>> from wradlib.trafo import decibel\n",
    "    >>> print(decibel(100.))\n",
    "    20.0\n",
    "    \"\"\"\n",
    "    return 10.0 * np.log10(x)\n",
    "\n",
    "\n",
    "def _idecibel(x):\n",
    "    \"\"\"Calculates the inverse of input decibel values\n",
    "\n",
    "    :math:`z=10^{x \\\\over 10}`\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    x : float or :class:`numpy:numpy.ndarray`\n",
    "\n",
    "    Examples\n",
    "    --------\n",
    "    >>> from wradlib.trafo import idecibel\n",
    "    >>> print(idecibel(10.))\n",
    "    10.0\n",
    "\n",
    "    \"\"\"\n",
    "    return 10.0 ** (x / 10.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8010d2b-a388-4f9d-b831-cbb708997f5b",
   "metadata": {},
   "source": [
    "## Function dictionaries\n",
    "\n",
    "To show the import of the functions, we put them in different dictionaries as we would get them via `entry_points`. \n",
    "\n",
    "This is what the downstream libraries would have to provide."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "90072b9e-63da-42ee-9780-cf6e5763f03f",
   "metadata": {},
   "outputs": [],
   "source": [
    "package_1_func = {\"trafo\": {\"decibel\": _decibel}}\n",
    "package_2_func = {\"trafo\": {\"idecibel\": _idecibel}}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5136dcc-41c5-4216-a1f6-c881e36a9c5c",
   "metadata": {},
   "source": [
    "## xradar internal functionality\n",
    "\n",
    "This is how xradar would need to treat that input data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6a3672f7-dd47-4320-ab5f-f49e470d22e1",
   "metadata": {},
   "outputs": [],
   "source": [
    "downstream_functions = [package_1_func, package_2_func]\n",
    "xradar_accessors = [\"trafo\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1834590-0e30-4642-92b6-c761a2ba647a",
   "metadata": {},
   "outputs": [],
   "source": [
    "package_functions = {}\n",
    "for accessor in xradar_accessors:\n",
    "    package_functions[accessor] = {}\n",
    "    for dfuncs in downstream_functions:\n",
    "        package_functions[accessor].update(dfuncs[accessor])\n",
    "print(package_functions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ccea2b6-3dbf-4195-a363-b3063ef88775",
   "metadata": {},
   "source": [
    "## Create and register accessor\n",
    "\n",
    "We bundle the different steps into one function, ``create_xradar_dataarray_accessor``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3a6f1530-3ab4-4d7e-8654-3fa9b3c40567",
   "metadata": {},
   "outputs": [],
   "source": [
    "for accessor in xradar_accessors:\n",
    "    xd.accessors.create_xradar_dataarray_accessor(accessor, package_functions[accessor])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6835753-a9f3-45e4-89be-29eeeda73d58",
   "metadata": {},
   "source": [
    "## Convert DBZH to linear and plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b660c563-0dfa-4617-b29d-02b1fc8522d1",
   "metadata": {},
   "outputs": [],
   "source": [
    "z = ds.DBZH.trafo.idecibel()\n",
    "z.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d5505b2-892d-452a-a22b-fa21783a3598",
   "metadata": {},
   "source": [
    "## Convert z to decibel and plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "44698c87-e97b-4538-9dcd-07f6821988c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "dbz = z.trafo.decibel()\n",
    "display(dbz)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "faf7c0a3-a975-42e9-ab13-93c725783964",
   "metadata": {},
   "outputs": [],
   "source": [
    "dbz.plot()"
   ]
  }
 ],
 "metadata": {
  "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}