deploy: a1afeef

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 73eb998e14fd2132a732d009e358aee8
+config: ce414a2ba73a00c5a7f97cc1fa7502a7
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/122338c6db2328ed9eeb5e9961344704/filter_and_interpolate.ipynb

@@ -0,0 +1,240 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Filtering and interpolation\n\nFilter out points with low confidence scores and interpolate over\nmissing values.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Imports\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from movement import sample_data\nfrom movement.filtering import filter_by_confidence, interpolate_over_time"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Load a sample dataset\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "ds = sample_data.fetch_sample_data(\"DLC_single-wasp.predictions.h5\")\nprint(ds)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can see that this dataset contains the 2D pose tracks and confidence\nscores for a single wasp, generated with DeepLabCut. There are 2 keypoints:\n\"head\" and \"stinger\".\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Visualise the pose tracks\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "pose_tracks = ds.pose_tracks.sel(individuals=\"individual_0\")\npose_tracks.plot.line(\n    x=\"time\", row=\"keypoints\", hue=\"space\", aspect=2, size=2.5\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can see that the pose tracks contain some implausible \"jumps\", such\nas the the big shift in the final second, and the \"spikes\" of the stinger\nnear the 14th second. Perhaps we can get rid of those based on the model's\nreported confidence scores?\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Visualise confidence scores\nThe confidence scores are stored in the ``confidence`` data variable.\nSince the predicted poses in this example have been generated by DeepLabCut,\nthe confidence scores should be likelihood values between 0 and 1.\nThat said, confidence scores are not standardised across pose\nestimation frameworks, and their ranges can vary. Therefore,\nit's always a good idea to inspect the actual confidence values in the data.\n\nLet's first look at a histogram of the confidence scores.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "ds.confidence.plot.hist(bins=20)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Based on the above histogram, we can confirm that the confidence scores\nindeed range between 0 and 1, with most values closer to 1. Now let's see how\nthey evolve over time.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "confidence = ds.confidence.sel(individuals=\"individual_0\")\nconfidence.plot.line(x=\"time\", row=\"keypoints\", aspect=2, size=2.5)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Encouragingly, some of the drops in confidence scores do seem to correspond\nto the implausible jumps and spikes we had seen in the pose tracks.\nWe can use that to our advantage.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Filter out points with low confidence\nWe can filter out points with confidence scores below a certain threshold.\nHere, we use ``threshold=0.6``. Points in the ``pose tracks`` data variable\nwith confidence scores below this threshold will be converted to NaN.\nThe ``print_report`` argument, which is True by default, reports the number\nof NaN values in the dataset before and after the filtering operation.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "ds_filtered = filter_by_confidence(ds, threshold=0.6, print_report=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can see that the filtering operation has introduced NaN values in the\n``pose_tracks`` data variable. Let's visualise the filtered pose tracks.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "pose_tracks_filtered = ds_filtered.pose_tracks.sel(individuals=\"individual_0\")\npose_tracks_filtered.plot.line(\n    x=\"time\", row=\"keypoints\", hue=\"space\", aspect=2, size=2.5\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Here we can see that gaps have appeared in the pose tracks, some of which\nare over the implausible jumps and spikes we had seen earlier. Moreover,\nmost gaps seem to be brief, lasting < 1 second.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Interpolate over missing values\nWe can interpolate over the gaps we've introduced in the pose tracks.\nHere we use the default linear interpolation method and ``max_gap=1``,\nmeaning that we will only interpolate over gaps of 1 second or shorter.\nSetting ``max_gap=None`` would interpolate over all gaps, regardless of\ntheir length, which should be used with caution as it can introduce\nspurious data. The ``print_report`` argument acts as described above.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "ds_interpolated = interpolate_over_time(\n    ds_filtered, method=\"linear\", max_gap=1, print_report=True\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We see that all NaN values have disappeared, meaning that all gaps were\nindeed shorter than 1 second. Let's visualise the interpolated pose tracks\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "pose_tracks_interpolated = ds_interpolated.pose_tracks.sel(\n    individuals=\"individual_0\"\n)\npose_tracks_interpolated.plot.line(\n    x=\"time\", row=\"keypoints\", hue=\"space\", aspect=2, size=2.5\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Log of processing steps\nSo, far we've processed the pose tracks first by filtering out points with\nlow confidence scores, and then by interpolating over missing values.\nThe order of these operations and the parameters with which they were\nperformed are saved in the ``log`` attribute of the dataset.\nThis is useful for keeping track of the processing steps that have been\napplied to the data.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "for log_entry in ds_interpolated.log:\n    print(log_entry)"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "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.11.8"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

_downloads/307bfbce3b04c474f9b3bd90e970e4c9/load_and_explore_poses.py

@@ -10,22 +10,22 @@
 # -------
 from matplotlib import pyplot as plt
 
-from movement import datasets
+from movement import sample_data
 from movement.io import load_poses
 
 # %%
 # Fetch an example dataset
 # ------------------------
 # Print a list of available datasets:
 
-for file_name in datasets.list_pose_data():
+for file_name in sample_data.list_sample_data():
     print(file_name)
 
 # %%
 # Fetch the path to an example dataset.
 # Feel free to replace this with the path to your own dataset.
 # e.g., ``file_path = "/path/to/my/data.h5"``)
-file_path = datasets.fetch_pose_data_path(
+file_path = sample_data.fetch_sample_data_path(
     "SLEAP_three-mice_Aeon_proofread.analysis.h5"
 )
 

_downloads/7f0c10d5c8b88801f34de1b2292ae010/load_and_explore_poses.ipynb

@@ -22,7 +22,7 @@
       },
       "outputs": [],
       "source": [
-        "from matplotlib import pyplot as plt\n\nfrom movement import datasets\nfrom movement.io import load_poses"
+        "from matplotlib import pyplot as plt\n\nfrom movement import sample_data\nfrom movement.io import load_poses"
       ]
     },
     {
@@ -40,7 +40,7 @@
       },
       "outputs": [],
       "source": [
-        "for file_name in datasets.list_pose_data():\n    print(file_name)"
+        "for file_name in sample_data.list_sample_data():\n    print(file_name)"
       ]
     },
     {
@@ -58,7 +58,7 @@
       },
       "outputs": [],
       "source": [
-        "file_path = datasets.fetch_pose_data_path(\n    \"SLEAP_three-mice_Aeon_proofread.analysis.h5\"\n)"
+        "file_path = sample_data.fetch_sample_data_path(\n    \"SLEAP_three-mice_Aeon_proofread.analysis.h5\"\n)"
       ]
     },
     {
@@ -186,7 +186,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.7"
+      "version": "3.11.8"
     }
   },
   "nbformat": 4,