{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Idealized Case 3: Tracking of a Test Blob in 3D" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This tutorial shows the most important steps of tracking with `tobac` using an idealized case:\n", "\n", "1. [Input Data](#1.-Input-Data)\n", "2. [Feature Detection](#2.-Feature-Detection)\n", "3. [Tracking / Trajectory Linking](#3.-Trajectory-Linking)\n", "4. [Segmentation](#4.-Segmentation)\n", "5. [Statistical Analysis](#5.-Statistical-Analysis)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Import Libraries\n", "\n", "We start by importing tobac:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "ExecuteTime": { "end_time": "2025-12-18T14:32:41.345715Z", "start_time": "2025-12-18T14:32:39.219387Z" }, "execution": { "iopub.execute_input": "2026-02-02T20:12:13.849742Z", "iopub.status.busy": "2026-02-02T20:12:13.849199Z", "iopub.status.idle": "2026-02-02T20:12:15.626049Z", "shell.execute_reply": "2026-02-02T20:12:15.625566Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "using tobac version 1.6.2\n" ] } ], "source": [ "import tobac\n", "\n", "print(\"using tobac version\", str(tobac.__version__))\n", "\n", "# We add testing here to create test dataset (typically not needed in standard applications).\n", "import tobac.testing" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We will also need matplotlib in inline-mode for plotting and numpy:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "ExecuteTime": { "end_time": "2025-12-18T14:32:41.582595Z", "start_time": "2025-12-18T14:32:41.360064Z" }, "execution": { "iopub.execute_input": "2026-02-02T20:12:15.644980Z", "iopub.status.busy": "2026-02-02T20:12:15.644736Z", "iopub.status.idle": "2026-02-02T20:12:15.777174Z", "shell.execute_reply": "2026-02-02T20:12:15.776801Z" } }, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "\n", "%matplotlib inline\n", "\n", "import numpy as np" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Tobac works with a Python package called `xarray`, which introduces `DataArrays`. In a nutshell these are `numpy`-arrays with intuitive dimensions, coordinates and meta-data. For a more extensive description have a look at the [xarray Documentation](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html#xarray.DataArray)." ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "ExecuteTime": { "end_time": "2025-12-18T14:32:41.592435Z", "start_time": "2025-12-18T14:32:41.589360Z" }, "execution": { "iopub.execute_input": "2026-02-02T20:12:15.779007Z", "iopub.status.busy": "2026-02-02T20:12:15.778883Z", "iopub.status.idle": "2026-02-02T20:12:15.780749Z", "shell.execute_reply": "2026-02-02T20:12:15.780251Z" } }, "outputs": [], "source": [ "import os\n", "CI = os.environ.get(\"CI\") == \"true\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 1. Input Data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "There are several utilities implemented in tobac to create simple examples of such arrays. In this tutorial we will use the function `make_simple_sample_data_3D_1blob()` to create a moving test blob in 3D:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "ExecuteTime": { "end_time": "2025-12-18T14:32:41.981557Z", "start_time": "2025-12-18T14:32:41.677326Z" }, "execution": { "iopub.execute_input": "2026-02-02T20:12:15.782069Z", "iopub.status.busy": "2026-02-02T20:12:15.781970Z", "iopub.status.idle": "2026-02-02T20:12:15.993981Z", "shell.execute_reply": "2026-02-02T20:12:15.993609Z" } }, "outputs": [ { "data": { "text/html": [ "
<xarray.DataArray 'w' (time: 25, z: 50, y: 50, x: 100)> Size: 50MB\n",
"array([[[[1.32998835e-001, 1.94482147e-001, 2.73237224e-001, ...,\n",
" 1.77393675e-066, 5.35682483e-068, 1.55419311e-069],\n",
" [1.94482147e-001, 2.84388247e-001, 3.99550583e-001, ...,\n",
" 2.59400038e-066, 7.83320239e-068, 2.27267263e-069],\n",
" [2.73237224e-001, 3.99550583e-001, 5.61347628e-001, ...,\n",
" 3.64443458e-066, 1.10052388e-067, 3.19298594e-069],\n",
" ...,\n",
" [1.26314698e-012, 1.84708036e-012, 2.59505110e-012, ...,\n",
" 1.68478381e-077, 5.08760627e-079, 1.47608385e-080],\n",
" [2.81846188e-013, 4.12139337e-013, 5.79034168e-013, ...,\n",
" 3.75926082e-078, 1.13519840e-079, 3.29358826e-081],\n",
" [6.04224961e-014, 8.83548849e-014, 1.24133983e-013, ...,\n",
" 8.05914474e-079, 2.43365084e-080, 7.06083078e-082]],\n",
"\n",
" [[1.52985076e-001, 2.23707719e-001, 3.14297620e-001, ...,\n",
" 2.04051297e-066, 6.16181524e-068, 1.78774761e-069],\n",
" [2.23707719e-001, 3.27124349e-001, 4.59592566e-001, ...,\n",
" 2.98381067e-066, 9.01032747e-068, 2.61419578e-069],\n",
" [3.14297620e-001, 4.59592566e-001, 6.45703469e-001, ...,\n",
" 4.19209761e-066, 1.26590379e-067, 3.67280806e-069],\n",
"...\n",
" 7.30390468e+000, 6.98950049e+000, 6.42636521e+000],\n",
" [1.57777643e-080, 7.31137562e-079, 3.25522453e-077, ...,\n",
" 8.17604954e+000, 7.82410297e+000, 7.19372482e+000],\n",
" [1.69692287e-080, 7.86349717e-079, 3.50104415e-077, ...,\n",
" 8.79346730e+000, 8.41494333e+000, 7.73696191e+000]],\n",
"\n",
" [[1.89968594e-102, 8.80309607e-101, 3.91937930e-099, ...,\n",
" 9.84418710e-022, 9.42043380e-022, 8.66144128e-022],\n",
" [1.39361834e-101, 6.45799173e-100, 2.87527467e-098, ...,\n",
" 7.22174090e-021, 6.91087354e-021, 6.35407314e-021],\n",
" [9.82277320e-101, 4.55184798e-099, 2.02660730e-097, ...,\n",
" 5.09016860e-020, 4.87105698e-020, 4.47860204e-020],\n",
" ...,\n",
" [1.50142782e-080, 6.95757810e-079, 3.09770419e-077, ...,\n",
" 7.78041044e+000, 7.44549456e+000, 6.84562042e+000],\n",
" [1.68071035e-080, 7.78836879e-079, 3.46759494e-077, ...,\n",
" 8.70945392e+000, 8.33454639e+000, 7.66304246e+000],\n",
" [1.80762989e-080, 8.37651067e-079, 3.72945180e-077, ...,\n",
" 9.36715192e+000, 8.96393310e+000, 8.24172027e+000]]]],\n",
" shape=(25, 50, 50, 100))\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 200B 2000-01-01T12:00:00 ... 2000-01-01T...\n",
" * z (z) float64 400B 0.0 1e+03 2e+03 ... 4.7e+04 4.8e+04 4.9e+04\n",
" * y (y) float64 400B 0.0 1e+03 2e+03 ... 4.7e+04 4.8e+04 4.9e+04\n",
" * x (x) float64 800B 0.0 1e+03 2e+03 ... 9.7e+04 9.8e+04 9.9e+04\n",
" latitude (y, x) float64 40kB 24.0 24.01 24.02 24.03 ... 24.97 24.98 24.99\n",
" longitude (y, x) float64 40kB 150.0 150.0 150.0 150.0 ... 150.5 150.5 150.5\n",
"Attributes:\n",
" units: m s-1<xarray.DataArray 'w' ()> Size: 8B\n",
"array(10.)\n",
"Attributes:\n",
" units: m s-1| \n", " | frame | \n", "idx | \n", "vdim | \n", "hdim_1 | \n", "hdim_2 | \n", "num | \n", "threshold_value | \n", "feature | \n", "time | \n", "timestr | \n", "z | \n", "y | \n", "x | \n", "latitude | \n", "longitude | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", "0 | \n", "1 | \n", "4.000000 | \n", "10.000000 | \n", "10.000000 | \n", "33 | \n", "9 | \n", "1 | \n", "2000-01-01 12:00:00 | \n", "2000-01-01 12:00:00 | \n", "4000.000000 | \n", "10000.000000 | \n", "10000.000000 | \n", "24.100000 | \n", "150.100000 | \n", "
| 1 | \n", "1 | \n", "1 | \n", "5.840909 | \n", "11.613636 | \n", "13.545455 | \n", "44 | \n", "9 | \n", "2 | \n", "2000-01-01 12:02:00 | \n", "2000-01-01 12:02:00 | \n", "5840.909091 | \n", "11613.636364 | \n", "13545.454545 | \n", "24.135455 | \n", "150.116136 | \n", "
| 2 | \n", "2 | \n", "1 | \n", "7.731707 | \n", "13.390244 | \n", "17.268293 | \n", "41 | \n", "9 | \n", "3 | \n", "2000-01-01 12:04:00 | \n", "2000-01-01 12:04:00 | \n", "7731.707317 | \n", "13390.243902 | \n", "17268.292683 | \n", "24.172683 | \n", "150.133902 | \n", "
| 3 | \n", "3 | \n", "1 | \n", "9.658537 | \n", "15.121951 | \n", "20.756098 | \n", "41 | \n", "9 | \n", "4 | \n", "2000-01-01 12:06:00 | \n", "2000-01-01 12:06:00 | \n", "9658.536585 | \n", "15121.951220 | \n", "20756.097561 | \n", "24.207561 | \n", "150.151220 | \n", "
| 4 | \n", "4 | \n", "1 | \n", "11.642857 | \n", "16.761905 | \n", "24.452381 | \n", "42 | \n", "9 | \n", "5 | \n", "2000-01-01 12:08:00 | \n", "2000-01-01 12:08:00 | \n", "11642.857143 | \n", "16761.904762 | \n", "24452.380952 | \n", "24.244524 | \n", "150.167619 | \n", "
| \n", " | frame | \n", "idx | \n", "vdim | \n", "hdim_1 | \n", "hdim_2 | \n", "num | \n", "threshold_value | \n", "feature | \n", "time | \n", "timestr | \n", "z | \n", "y | \n", "x | \n", "latitude | \n", "longitude | \n", "cell | \n", "time_cell | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", "0 | \n", "1 | \n", "4.000000 | \n", "10.000000 | \n", "10.000000 | \n", "33 | \n", "9 | \n", "1 | \n", "2000-01-01 12:00:00 | \n", "2000-01-01 12:00:00 | \n", "4000.000000 | \n", "10000.000000 | \n", "10000.000000 | \n", "24.100000 | \n", "150.100000 | \n", "1 | \n", "0 days 00:00:00 | \n", "
| 1 | \n", "1 | \n", "1 | \n", "5.840909 | \n", "11.613636 | \n", "13.545455 | \n", "44 | \n", "9 | \n", "2 | \n", "2000-01-01 12:02:00 | \n", "2000-01-01 12:02:00 | \n", "5840.909091 | \n", "11613.636364 | \n", "13545.454545 | \n", "24.135455 | \n", "150.116136 | \n", "1 | \n", "0 days 00:02:00 | \n", "
| 2 | \n", "2 | \n", "1 | \n", "7.731707 | \n", "13.390244 | \n", "17.268293 | \n", "41 | \n", "9 | \n", "3 | \n", "2000-01-01 12:04:00 | \n", "2000-01-01 12:04:00 | \n", "7731.707317 | \n", "13390.243902 | \n", "17268.292683 | \n", "24.172683 | \n", "150.133902 | \n", "1 | \n", "0 days 00:04:00 | \n", "
| 3 | \n", "3 | \n", "1 | \n", "9.658537 | \n", "15.121951 | \n", "20.756098 | \n", "41 | \n", "9 | \n", "4 | \n", "2000-01-01 12:06:00 | \n", "2000-01-01 12:06:00 | \n", "9658.536585 | \n", "15121.951220 | \n", "20756.097561 | \n", "24.207561 | \n", "150.151220 | \n", "1 | \n", "0 days 00:06:00 | \n", "
| 4 | \n", "4 | \n", "1 | \n", "11.642857 | \n", "16.761905 | \n", "24.452381 | \n", "42 | \n", "9 | \n", "5 | \n", "2000-01-01 12:08:00 | \n", "2000-01-01 12:08:00 | \n", "11642.857143 | \n", "16761.904762 | \n", "24452.380952 | \n", "24.244524 | \n", "150.167619 | \n", "1 | \n", "0 days 00:08:00 | \n", "
<xarray.DataArray 'segmentation_mask' (time: 25, z: 50, y: 50, x: 100)> Size: 50MB\n",
"array([[[[ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" ...,\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0]],\n",
"\n",
" [[ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" ...,\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0]],\n",
"\n",
" [[ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" ...,\n",
"...\n",
" ...,\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0]],\n",
"\n",
" [[ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" ...,\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0]],\n",
"\n",
" [[ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" ...,\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 0, 0, 0],\n",
" [ 0, 0, 0, ..., 25, 0, 0]]]], shape=(25, 50, 50, 100))\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 200B 2000-01-01T12:00:00 ... 2000-01-01T...\n",
" * z (z) float64 400B 0.0 1e+03 2e+03 ... 4.7e+04 4.8e+04 4.9e+04\n",
" * y (y) float64 400B 0.0 1e+03 2e+03 ... 4.7e+04 4.8e+04 4.9e+04\n",
" * x (x) float64 800B 0.0 1e+03 2e+03 ... 9.7e+04 9.8e+04 9.9e+04\n",
" latitude (y, x) float64 40kB 24.0 24.01 24.02 24.03 ... 24.97 24.98 24.99\n",
" longitude (y, x) float64 40kB 150.0 150.0 150.0 150.0 ... 150.5 150.5 150.5\n",
"Attributes:\n",
" threshold: 9| \n", " | frame | \n", "idx | \n", "vdim | \n", "hdim_1 | \n", "hdim_2 | \n", "num | \n", "threshold_value | \n", "feature | \n", "time | \n", "timestr | \n", "z | \n", "y | \n", "x | \n", "latitude | \n", "longitude | \n", "mean | \n", "total | \n", "max | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", "0 | \n", "1 | \n", "4.000000 | \n", "10.000000 | \n", "10.000000 | \n", "33 | \n", "9 | \n", "1 | \n", "2000-01-01 12:00:00 | \n", "2000-01-01 12:00:00 | \n", "4000.000000 | \n", "10000.000000 | \n", "10000.000000 | \n", "24.100000 | \n", "150.100000 | \n", "9.333259 | \n", "531.995777 | \n", "10.0 | \n", "
| 1 | \n", "1 | \n", "1 | \n", "5.840909 | \n", "11.613636 | \n", "13.545455 | \n", "44 | \n", "9 | \n", "2 | \n", "2000-01-01 12:02:00 | \n", "2000-01-01 12:02:00 | \n", "5840.909091 | \n", "11613.636364 | \n", "13545.454545 | \n", "24.135455 | \n", "150.116136 | \n", "9.400239 | \n", "470.011963 | \n", "9.946384 | \n", "
| 2 | \n", "2 | \n", "1 | \n", "7.731707 | \n", "13.390244 | \n", "17.268293 | \n", "41 | \n", "9 | \n", "3 | \n", "2000-01-01 12:04:00 | \n", "2000-01-01 12:04:00 | \n", "7731.707317 | \n", "13390.243902 | \n", "17268.292683 | \n", "24.172683 | \n", "150.133902 | \n", "9.387958 | \n", "478.785843 | \n", "9.961036 | \n", "
| 3 | \n", "3 | \n", "1 | \n", "9.658537 | \n", "15.121951 | \n", "20.756098 | \n", "41 | \n", "9 | \n", "4 | \n", "2000-01-01 12:06:00 | \n", "2000-01-01 12:06:00 | \n", "9658.536585 | \n", "15121.951220 | \n", "20756.097561 | \n", "24.207561 | \n", "150.151220 | \n", "9.391814 | \n", "469.590716 | \n", "9.98018 | \n", "
| 4 | \n", "4 | \n", "1 | \n", "11.642857 | \n", "16.761905 | \n", "24.452381 | \n", "42 | \n", "9 | \n", "5 | \n", "2000-01-01 12:08:00 | \n", "2000-01-01 12:08:00 | \n", "11642.857143 | \n", "16761.904762 | \n", "24452.380952 | \n", "24.244524 | \n", "150.167619 | \n", "9.415543 | \n", "451.946046 | \n", "9.932072 | \n", "