tutorials/3-advanced-topics/DTAT306_properties.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# deeptrack.properties\n",
        "\n",
        "<a href=\"https://colab.research.google.com/github/DeepTrackAI/DeepTrack2/blob/develop/tutorials/3-advanced-topics/DTAT306_properties.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {},
      "outputs": [],
      "source": [
        "# !pip install deeptrack  # Uncomment if running on Colab/Kaggle."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This advanced tutorial introduces the module deeptrack.properties."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 1. What is a property?\n",
        "\n",
        "Each feature (instance of the class `Feature`, see [features_example](DTAT301_features.ipynb)) can have several properties (instances of the class `Property`). These properties can be constants, functions, lists, dictionaries, iterators, or slices, providing flexibility in defining and controlling different aspects of the system being modelled.\n",
        "\n",
        "A propety has a value accessible through the field `current_value`, whose data type is not restricted. \n",
        "This value is updated through a sampling rule (method `.update()`), which is passed to the class constructor on initialization. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {},
      "outputs": [],
      "source": [
        "import numpy as np"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.1. What is a sampling rule?\n",
        "\n",
        "The sampling rule determines how the value of a property is updated upon calling `.update()`.\n",
        "A sampling rule is defined when an instance of the class `Property` is created and can be of any type. \n",
        "When calling `.update()`, the value of the property is updated according to the first of the following that applies:\n",
        "    \n",
        "1.  If the sampling rule has a method `.sample()`, call `.sample()` and return the output.\n",
        "\n",
        "2.  If the sampling rule is a ``dict``, sample each value and combine the result into a new ``dict`` using the original keys. \n",
        "\n",
        "3.  If the sampling rule is a ``list``, sample each element of the list and combine the result into a new ``list``.\n",
        "\n",
        "4.  If the sampling rule is an iterable, return the next value. If the iterable is exhausted, the value of the property is not changed.\n",
        "\n",
        "5.  If the sampling rule is callable, call it and return the result.\n",
        "\n",
        "6.  If none of the above apply, return the sampling rule itself."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {},
      "outputs": [],
      "source": [
        "from deeptrack.properties import Property, PropertyDict, SequentialProperty"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.2. Property with a Constant Value\n",
        "\n",
        "The simplest example of a property is one that does not change during an update call.\n",
        "This is commonly either a number or a tuple, but can be any data type that will be evaluated by case 6 above.\n",
        "If you want to have a constant property with a value that would be evaluated by cases 1-5 (e.g., a list or a function), you can  wrap it as the output of a lambda function."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is 1\n",
            "The current value of the property is 1\n"
          ]
        }
      ],
      "source": [
        "# Number.\n",
        "\n",
        "P = Property(1)\n",
        "print(f\"The current value of the property is {P()}\")\n",
        "\n",
        "P.update()  # Numbers are not changed after an update() call.\n",
        "print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is (1, [2, 3], None)\n",
            "The current value of the property is (1, [2, 3], None)\n"
          ]
        }
      ],
      "source": [
        "# Tuple.\n",
        "\n",
        "P = Property((1, [2, 3], None))\n",
        "print(f\"The current value of the property is {P()}\")\n",
        "\n",
        "P.update()  # Tuples are not changed after an update() call.\n",
        "print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is [<built-in method rand of numpy.random.mtrand.RandomState object at 0x10b30ed40>, 1, {}]\n",
            "The current value of the property is [<built-in method rand of numpy.random.mtrand.RandomState object at 0x10b30ed40>, 1, {}]\n"
          ]
        }
      ],
      "source": [
        "# Wrapped list.\n",
        "\n",
        "P = Property(lambda: [np.random.rand, 1, {}])\n",
        "print(f\"The current value of the property is {P()}\")\n",
        "\n",
        "P.update()  # Objects wrapped in functions are not changed by an update() call.\n",
        "print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.3. Property with a Discrete Random Value \n",
        "\n",
        "Discrete randomness can be achieved by a function (case 5)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is 9\n",
            "The current value of the property is 0\n",
            "The current value of the property is 0\n",
            "The current value of the property is 2\n",
            "The current value of the property is 3\n"
          ]
        }
      ],
      "source": [
        "# Function.\n",
        "\n",
        "P = Property(lambda: np.random.randint(0, 10))\n",
        "\n",
        "for _ in range(5): \n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is 0\n",
            "The current value of the property is 0\n",
            "The current value of the property is 0\n",
            "The current value of the property is 1\n",
            "The current value of the property is 0\n"
          ]
        }
      ],
      "source": [
        "# Binary choice.\n",
        "\n",
        "P = Property(lambda: 1 if np.random.rand() > 0.75 else 0)\n",
        "\n",
        "for _ in range(5): \n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.4. Property with a Continuous Random Value\n",
        "\n",
        "Continuous randomness is typically achieved by passing a function that returns a continuous random value. This function should take no input, as noted in case 5. To use a function that needs arguments, wrap it in a function that calls it with the correct arguments."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is 0.6058058486216974\n",
            "The current value of the property is 0.4388130582114753\n",
            "The current value of the property is 0.4492343759700439\n",
            "The current value of the property is 0.43076786487677377\n",
            "The current value of the property is 0.5294829032012791\n"
          ]
        }
      ],
      "source": [
        "# Function with no input.\n",
        "\n",
        "P = Property(np.random.rand)\n",
        "\n",
        "for _ in range(5):\n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is -2.7800167909302074\n",
            "The current value of the property is -4.99826898249571\n",
            "The current value of the property is 9.239257264425211\n",
            "The current value of the property is 10.638607727647866\n",
            "The current value of the property is 7.443379615451991\n"
          ]
        }
      ],
      "source": [
        "# Wrapped function.\n",
        "\n",
        "P = Property(lambda: np.random.normal(1, 5))\n",
        "\n",
        "for _ in range(5):\n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.5. Property with a Deterministically Changing Value\n",
        "\n",
        "Deterministically changing properties can be achieved using either an iterator (case 4) or a function (case 5). For the output of a function to change deterministically between calls, it should reference some variable outside its definition. Once an iterator has been exhausted, it will always return its last value."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is 1\n",
            "The current value of the property is 2\n",
            "The current value of the property is 3\n",
            "The current value of the property is 4\n",
            "The current value of the property is 5\n",
            "The current value of the property is 5\n",
            "The current value of the property is 5\n",
            "The current value of the property is 5\n",
            "The current value of the property is 5\n",
            "The current value of the property is 5\n"
          ]
        }
      ],
      "source": [
        "# Iterator.\n",
        "\n",
        "P = Property(iter([1, 2, 3, 4, 5]))\n",
        "\n",
        "for _ in range(10):\n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current value of the property is [1, 1, 2]\n",
            "The current value of the property is [1, 1, 2, 3]\n",
            "The current value of the property is [1, 1, 2, 3, 5]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13, 21]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13, 21, 34]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]\n",
            "The current value of the property is [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144]\n"
          ]
        }
      ],
      "source": [
        "# Function.\n",
        "\n",
        "fibbonacci = [1, 1]\n",
        "\n",
        "def fibbonacci_sequence():\n",
        "    fibbonacci.append(fibbonacci[-2] + fibbonacci[-1])\n",
        "    return fibbonacci\n",
        "\n",
        "P = Property(fibbonacci_sequence)\n",
        "\n",
        "for _ in range(10):\n",
        "    P.update()\n",
        "    print(f\"The current value of the property is {P()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 1.6. Property with Dependent Value\n",
        "\n",
        "The value of a property can be dependent on the value on some other property. It does this by accepting some keyword argument corresponding to the name of the independent property. Instances of `Feature` will handle this automatically."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 13,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current independent property is 0.6047967671299797\n",
            "The current dependent property is 1.6047967671299797\n",
            "\n",
            "The current independent property is 0.9632829097510287\n",
            "The current dependent property is 1.9632829097510287\n",
            "\n",
            "The current independent property is 0.5707308224509307\n",
            "The current dependent property is 1.5707308224509307\n",
            "\n",
            "The current independent property is 0.17336784973310793\n",
            "The current dependent property is 1.173367849733108\n",
            "\n",
            "The current independent property is 0.2129111133514252\n",
            "The current dependent property is 1.2129111133514252\n",
            "\n"
          ]
        }
      ],
      "source": [
        "random_number = Property(lambda: np.random.rand())\n",
        "\n",
        "def get_dependent_number():\n",
        "    return random_number() + 1\n",
        "\n",
        "dependent_number = Property(get_dependent_number)\n",
        "\n",
        "# Link the properties with add_dependency() or add_child().\n",
        "# PropertyDict (see below) automatically links the properties.\n",
        "dependent_number.add_dependency(random_number)  # Alternative 1.\n",
        "# random_number.add_child(dependent_number)  # Alternative 2.\n",
        "\n",
        "for _ in range(5):\n",
        "    dependent_number.update()\n",
        "    \n",
        "    print(f\"The current independent property is {random_number()}\")\n",
        "    print(f\"The current dependent property is {dependent_number()}\\n\")\n",
        "    \n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 3. What is a PropertyDict?\n",
        "\n",
        "Another class contained in the module deeptrack.properties is `PropertyDict`. This is a dictionary of properties (keys: name of properties; values: properties) complemented by utility methods to manage collections of properties. These include:\n",
        "\n",
        "- `.current_value_dict()`, which creates and returns a dictionary with the current value of all properties in the PropertyDict (keys: name of properties; values: current values of the properties).\n",
        "\n",
        "- `.update()`, which calls the method `.update()` on all properties in the PropertyDict.\n",
        "\n",
        "- `.sample()`, which calls the method `.sample()` on all properties in the PropertyDict, and creates and returns a dictionary from the output (keys: name of properties; values: sample outputs of the properties).\n",
        "\n",
        "Importantly, `PropertyDict` automatically links the properties within a property dictionary.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The current properties in property_dict are {'foo': 'foo', 'barorbaz': 'baz', 'foobarorbaz': 'foobaz'}\n",
            "The current properties in property_dict are {'foo': 'foo', 'barorbaz': 'baz', 'foobarorbaz': 'foobaz'}\n",
            "The current properties in property_dict are {'foo': 'foo', 'barorbaz': 'bar', 'foobarorbaz': 'foobar'}\n",
            "The current properties in property_dict are {'foo': 'foo', 'barorbaz': 'bar', 'foobarorbaz': 'foobar'}\n",
            "The current properties in property_dict are {'foo': 'foo', 'barorbaz': 'baz', 'foobarorbaz': 'foobaz'}\n"
          ]
        }
      ],
      "source": [
        "property_dict = PropertyDict(\n",
        "    foo=\"foo\",\n",
        "    barorbaz=lambda:np.random.choice([\"bar\", \"baz\"]),\n",
        "    foobarorbaz=lambda foo, barorbaz: foo + barorbaz,\n",
        ")\n",
        "\n",
        "for _ in range(5):\n",
        "    property_dict.update()\n",
        "    print(f\"The current properties in property_dict are {property_dict()}\")"
      ]
    }
  ],
  "metadata": {
    "file_extension": ".py",
    "kernelspec": {
      "display_name": "py_env_book",
      "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.15"
    },
    "mimetype": "text/x-python",
    "name": "python",
    "npconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": 3
  },
  "nbformat": 4,
  "nbformat_minor": 2
}