jupyter/4dobc-customization.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "## 4D Object By Change - Customizing the algorithm"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "The 4D-OBC implementation provided by `py4dgeo` can be customized similarly to [how M3C2 is customized](customization.ipynb). The fundamental idea is to create your own algorithm class derived from `py4dgeo`'s `RegionGrowingAlgorithm` class and override only those parts of the algorithm that you want to change. This notebook introduces the currently existing customization points."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "import py4dgeo\n",
    "import numpy as np\n",
    "\n",
    "import _py4dgeo  # The C++ bindings module for py4dgeo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load test data\n",
    "analysis = py4dgeo.SpatiotemporalAnalysis(\"synthetic.zip\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We are disabling log messages on this tutorial to increase the readability of the output\n",
    "import logging\n",
    "\n",
    "logging.disable()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "### Distance Measure"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "By default, 4D-OBC uses a normalized Dynamic Time Warping distance measure. You can provide your own Python function, although all the same warnings as with M3C2 apply: Python code will be significantly slower compared to C++ implementations and will be run sequentially even if you are using OpenMP."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7",
   "metadata": {},
   "outputs": [],
   "source": [
    "def custom_distance(params: _py4dgeo.TimeseriesDistanceFunctionData):\n",
    "    mask = ~np.isnan(params.ts1) & ~np.isnan(params.ts2)\n",
    "    if not np.any(mask):\n",
    "        return np.nan\n",
    "\n",
    "    # Mask the two input arrays\n",
    "    masked_ts1 = params.ts1[mask]\n",
    "    masked_ts2 = params.ts2[mask]\n",
    "\n",
    "    return np.sum(np.abs(masked_ts1 - masked_ts2)) / np.sum(\n",
    "        np.abs(np.maximum(masked_ts1, masked_ts2))\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8",
   "metadata": {},
   "outputs": [],
   "source": [
    "class CustomDistance4DOBC(py4dgeo.RegionGrowingAlgorithm):\n",
    "    def distance_measure(self):\n",
    "        return custom_distance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "analysis.invalidate_results()\n",
    "objects = CustomDistance4DOBC(\n",
    "    neighborhood_radius=2.0,\n",
    "    seed_subsampling=20,\n",
    ").run(analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "The `params` data structure passed to the distance function contains the following fields:\n",
    "* `ts1` and `ts2` are the time series to compare which may include `NaN` values\n",
    "* `norm1` and `norm2` which are normalization factors"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11",
   "metadata": {},
   "source": [
    "### Prioritizing seeds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "The 4D-OBC algorithm finds a number of seed locations for region growing and then prioritizes these seeds by sorting them according to a criterion. You can pass your own criterium like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13",
   "metadata": {},
   "outputs": [],
   "source": [
    "def sorting_criterion(seed):\n",
    "    # Choose a random score, resulting in random seed order\n",
    "    return np.random.rand()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14",
   "metadata": {},
   "outputs": [],
   "source": [
    "class CustomSeedSorting(py4dgeo.RegionGrowingAlgorithm):\n",
    "    def seed_sorting_scorefunction(self):\n",
    "        return sorting_criterion"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15",
   "metadata": {},
   "outputs": [],
   "source": [
    "analysis.invalidate_results()\n",
    "objects = CustomSeedSorting(\n",
    "    neighborhood_radius=2.0,\n",
    "    seed_subsampling=20,\n",
    ").run(analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16",
   "metadata": {},
   "source": [
    "### Rejecting grown objects"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "After the region growing is done, the algorithm class calls it method `filter_objects` to check whether the object should be used or discarded. The method must return `True` (keep) or `False` (discard):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18",
   "metadata": {},
   "outputs": [],
   "source": [
    "class RejectSmallObjects(py4dgeo.RegionGrowingAlgorithm):\n",
    "    def filter_objects(self, obj):\n",
    "        return len(obj.indices) > 10"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "19",
   "metadata": {},
   "outputs": [],
   "source": [
    "analysis.invalidate_results()\n",
    "objects = RejectSmallObjects(\n",
    "    neighborhood_radius=2.0,\n",
    "    seed_subsampling=20,\n",
    ").run(analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "### Seed point detection"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21",
   "metadata": {},
   "source": [
    "If you would like to run an entirely different algorithm to determine the seeds for region growing, you can do so by overriding `find_seedpoints`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "22",
   "metadata": {},
   "outputs": [],
   "source": [
    "from py4dgeo.segmentation import RegionGrowingSeed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "23",
   "metadata": {},
   "outputs": [],
   "source": [
    "class DifferentSeeds(py4dgeo.RegionGrowingAlgorithm):\n",
    "    def find_seedpoints(self):\n",
    "        # Use one seed for corepoint 0 and the entire time interval\n",
    "        return [RegionGrowingSeed(0, 0, self.analysis.distances.shape[1] - 1)]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24",
   "metadata": {},
   "outputs": [],
   "source": [
    "analysis.invalidate_results()\n",
    "objects = DifferentSeeds(\n",
    "    neighborhood_radius=2.0,\n",
    "    seed_subsampling=20,\n",
    ").run(analysis)"
   ]
  }
 ],
 "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.10.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}