python_udf.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6af3ac5b",
   "metadata": {},
   "source": [
    "## Simple UDF sample\n",
    "\n",
    "This notebook shows how to apply [user defined functions](https://open-eo.github.io/openeo-python-client/udf.html).\n",
    "This is a powerfull concept that allows you to combine arbitrary Python code with your predefined openEO processes.\n",
    "\n",
    "We start by setting up a basic data cube:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d937b336-6f3b-4e79-9502-9a1ad2e0a38d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0.16.0a3'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import openeo\n",
    "\n",
    "openeo.client_version()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3d6d8eda-f89e-4cbb-8ada-5bb078389ca0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Authenticated using refresh token.\n"
     ]
    }
   ],
   "source": [
    "# Create connection to openEO back-end\n",
    "connection = openeo.connect(\"openeo.cloud\").authenticate_oidc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "7e214675-ee6f-417d-bc4b-51e99b7d1349",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load initial data cube.\n",
    "s2_cube = connection.load_collection(\n",
    "    \"SENTINEL2_L2A\",\n",
    "    spatial_extent={\"west\": 4.00, \"south\": 51.04, \"east\": 4.01, \"north\": 51.05},\n",
    "    temporal_extent=[\"2022-03-01\", \"2022-03-31\"],\n",
    "    bands=[\"B02\", \"B03\", \"B04\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe1e0548",
   "metadata": {},
   "source": [
    "Now we load the UDF, it needs to be provided to the backend as plain text, so we store it in a separate file next to this notebook. This makes it easier to edit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "f6d1b8ba-ffae-451c-8c46-ae11a68f6fbd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "from openeo.udf import XarrayDataCube\n",
      "\n",
      "def apply_datacube(cube: XarrayDataCube, context: dict) -> XarrayDataCube:\n",
      "    \"\"\"\n",
      "    A trivial UDF that scales values, can also be done without UDF!\n",
      "    \"\"\"\n",
      "    array = cube.get_array()\n",
      "    array.values = 0.0001 * array.values\n",
      "    return cube\n"
     ]
    }
   ],
   "source": [
    "simple_udf = openeo.UDF.from_file(\"simple_udf.py\")\n",
    "\n",
    "print(simple_udf.code)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7de9a83d",
   "metadata": {},
   "source": [
    "We can now apply the UDF to each pixel, using it as child process in the `apply` process:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e0ad699e-7ff1-4a0b-9321-0218e7fe854e",
   "metadata": {},
   "outputs": [],
   "source": [
    "rescaled = s2_cube.apply(simple_udf)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "039874d9-ce38-4307-8354-e7fa7906db72",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 16.3 ms, sys: 8.44 ms, total: 24.8 ms\n",
      "Wall time: 40.7 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "rescaled.download(\"apply-udf-scaling.nc\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "openeo-client-venv3.9",
   "language": "python",
   "name": "openeo-3.9"
  },
  "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}