deploy: f4f46df

_downloads/07f4b1b69497c93530bbe772d7eb535a/smooth.py

@@ -109,7 +109,7 @@ def plot_raw_and_smooth_timeseries_and_psd(
 # Smoothing with a median filter
 # ------------------------------
 # Using the
-# :py:meth:`median_filter()\
+# :meth:`median_filter()\
 # <movement.move_accessor.MovementDataset.filtering_wrapper>`
 # method of the ``move`` accessor,
 # we apply a rolling window median filter over a 0.1-second window
@@ -125,13 +125,13 @@ def plot_raw_and_smooth_timeseries_and_psd(
 
 # %%
 # .. note::
-#    The ``move`` accessor :py:meth:`median_filter()\
+#    The ``move`` accessor :meth:`median_filter()\
 #    <movement.move_accessor.MovementDataset.filtering_wrapper>`
 #    method is a convenience method that applies
-#    :py:func:`movement.filtering.median_filter`
+#    :func:`movement.filtering.median_filter`
 #    to the ``position`` data variable.
 #    The equivalent function call using the
-#    :py:mod:`movement.filtering` module would be:
+#    :mod:`movement.filtering` module would be:
 #
 #    .. code-block:: python
 #
@@ -249,11 +249,11 @@ def plot_raw_and_smooth_timeseries_and_psd(
 # Smoothing with a Savitzky-Golay filter
 # --------------------------------------
 # Here we use the
-# :py:meth:`savgol_filter()\
+# :meth:`savgol_filter()\
 # <movement.move_accessor.MovementDataset.filtering_wrapper>`
 # method of the ``move`` accessor, which is a convenience method that applies
-# :py:func:`movement.filtering.savgol_filter`
-# (a wrapper around :py:func:`scipy.signal.savgol_filter`),
+# :func:`movement.filtering.savgol_filter`
+# (a wrapper around :func:`scipy.signal.savgol_filter`),
 # to the ``position`` data variable.
 # The Savitzky-Golay filter is a polynomial smoothing filter that can be
 # applied to time series data on a rolling window basis.

_downloads/085258163d1f42f74bf76da18a848b11/compute_kinematics.ipynb

@@ -22,7 +22,7 @@
       },
       "outputs": [],
       "source": [
-        "import numpy as np\n\n# For interactive plots: install ipympl with `pip install ipympl` and uncomment\n# the following line in your notebook\n# %matplotlib widget\nfrom matplotlib import pyplot as plt\n\nfrom movement import sample_data"
+        "# For interactive plots: install ipympl with `pip install ipympl` and uncomment\n# the following line in your notebook\n# %matplotlib widget\nfrom matplotlib import pyplot as plt\n\nfrom movement import sample_data\nfrom movement.utils.vector import compute_norm"
       ]
     },
     {
@@ -122,7 +122,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "We can also easily plot the components of the position vector against time\nusing ``xarray``'s built-in plotting methods. We use\n:py:meth:`xarray.DataArray.squeeze` to\nremove the dimension of length 1 from the data (the ``keypoints`` dimension).\n\n"
+        "We can also easily plot the components of the position vector against time\nusing ``xarray``'s built-in plotting methods. We use\n:meth:`xarray.DataArray.squeeze` to\nremove the dimension of length 1 from the data (the ``keypoints`` dimension).\n\n"
       ]
     },
     {
@@ -172,7 +172,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Notice that we could also compute the displacement (and all the other\nkinematic variables) using the :py:mod:`movement.analysis.kinematics` module:\n\n"
+        "Notice that we could also compute the displacement (and all the other\nkinematic variables) using the :mod:`movement.analysis.kinematics` module:\n\n"
       ]
     },
     {
@@ -283,7 +283,7 @@
       },
       "outputs": [],
       "source": [
-        "# length of each displacement vector\ndisplacement_vectors_lengths = np.linalg.norm(\n    displacement.sel(individuals=mouse_name, space=[\"x\", \"y\"]).squeeze(),\n    axis=1,\n)\n\n# sum of all displacement vectors\ntotal_displacement = np.sum(displacement_vectors_lengths, axis=0)  # in pixels\n\nprint(\n    f\"The mouse {mouse_name}'s trajectory is {total_displacement:.2f} \"\n    \"pixels long\"\n)"
+        "# length of each displacement vector\ndisplacement_vectors_lengths = compute_norm(\n    displacement.sel(individuals=mouse_name)\n)\n\n# sum the lengths of all displacement vectors (in pixels)\ntotal_displacement = displacement_vectors_lengths.sum(dim=\"time\").values[0]\n\nprint(\n    f\"The mouse {mouse_name}'s trajectory is {total_displacement:.2f} \"\n    \"pixels long\"\n)"
       ]
     },
     {
@@ -315,7 +315,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "We can plot the components of the velocity vector against time\nusing ``xarray``'s built-in plotting methods. We use\n:py:meth:`xarray.DataArray.squeeze` to\nremove the dimension of length 1 from the data (the ``keypoints`` dimension).\n\n"
+        "We can plot the components of the velocity vector against time\nusing ``xarray``'s built-in plotting methods. We use\n:meth:`xarray.DataArray.squeeze` to\nremove the dimension of length 1 from the data (the ``keypoints`` dimension).\n\n"
       ]
     },
     {
@@ -340,7 +340,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "We can also visualise the speed, as the norm of the velocity vector:\n\n"
+        "We can also visualise the speed, as the magnitude (norm)\nof the velocity vector:\n\n"
       ]
     },
     {
@@ -351,7 +351,7 @@
       },
       "outputs": [],
       "source": [
-        "fig, axes = plt.subplots(3, 1, sharex=True, sharey=True)\nfor mouse_name, ax in zip(velocity.individuals.values, axes, strict=False):\n    # compute the norm of the velocity vector for one mouse\n    speed_one_mouse = np.linalg.norm(\n        velocity.sel(individuals=mouse_name, space=[\"x\", \"y\"]).squeeze(),\n        axis=1,\n    )\n    # plot speed against time\n    ax.plot(speed_one_mouse)\n    ax.set_title(mouse_name)\n    ax.set_xlabel(\"time (s)\")\n    ax.set_ylabel(\"speed (px/s)\")\nfig.tight_layout()"
+        "fig, axes = plt.subplots(3, 1, sharex=True, sharey=True)\nfor mouse_name, ax in zip(velocity.individuals.values, axes, strict=False):\n    # compute the magnitude of the velocity vector for one mouse\n    speed_one_mouse = compute_norm(velocity.sel(individuals=mouse_name))\n    # plot speed against time\n    ax.plot(speed_one_mouse)\n    ax.set_title(mouse_name)\n    ax.set_xlabel(\"time (s)\")\n    ax.set_ylabel(\"speed (px/s)\")\nfig.tight_layout()"
       ]
     },
     {
@@ -419,7 +419,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "The norm of the acceleration vector is the magnitude of the\nacceleration.\nWe can also represent this for each individual.\n\n"
+        "The can also represent the magnitude (norm) of the acceleration vector\nfor each individual:\n\n"
       ]
     },
     {
@@ -430,7 +430,7 @@
       },
       "outputs": [],
       "source": [
-        "fig, axes = plt.subplots(3, 1, sharex=True, sharey=True)\nfor mouse_name, ax in zip(accel.individuals.values, axes, strict=False):\n    # compute norm of the acceleration vector for one mouse\n    accel_one_mouse = np.linalg.norm(\n        accel.sel(individuals=mouse_name, space=[\"x\", \"y\"]).squeeze(),\n        axis=1,\n    )\n\n    # plot acceleration against time\n    ax.plot(accel_one_mouse)\n    ax.set_title(mouse_name)\n    ax.set_xlabel(\"time (s)\")\n    ax.set_ylabel(\"accel (px/s**2)\")\nfig.tight_layout()"
+        "fig, axes = plt.subplots(3, 1, sharex=True, sharey=True)\nfor mouse_name, ax in zip(accel.individuals.values, axes, strict=False):\n    # compute magnitude of the acceleration vector for one mouse\n    accel_one_mouse = compute_norm(accel.sel(individuals=mouse_name))\n\n    # plot acceleration against time\n    ax.plot(accel_one_mouse)\n    ax.set_title(mouse_name)\n    ax.set_xlabel(\"time (s)\")\n    ax.set_ylabel(\"accel (px/s**2)\")\nfig.tight_layout()"
       ]
     }
   ],

_downloads/122338c6db2328ed9eeb5e9961344704/filter_and_interpolate.ipynb

@@ -54,7 +54,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Visualise the pose tracks\nSince the data contains only a single wasp, we use\n:py:meth:`xarray.DataArray.squeeze` to remove\nthe dimension of length 1 from the data (the ``individuals`` dimension).\n\n"
+        "## Visualise the pose tracks\nSince the data contains only a single wasp, we use\n:meth:`xarray.DataArray.squeeze` to remove\nthe dimension of length 1 from the data (the ``individuals`` dimension).\n\n"
       ]
     },
     {
@@ -79,7 +79,7 @@
       "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. As before, we use\n:py:meth:`xarray.DataArray.squeeze` to remove the ``individuals`` dimension\nfrom the data.\n\n"
+        "## 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. As before, we use\n:meth:`xarray.DataArray.squeeze` to remove the ``individuals`` dimension\nfrom the data.\n\n"
       ]
     },
     {
@@ -122,7 +122,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Filter out points with low confidence\nUsing the\n:py:meth:`filter_by_confidence()\\\n<movement.move_accessor.MovementDataset.filtering_wrapper>`\nmethod of the ``move`` accessor,\nwe can filter out points with confidence scores below a certain threshold.\nThe default ``threshold=0.6`` will be used when ``threshold`` is not\nprovided.\nThis method will also report the number of NaN values in the dataset before\nand after the filtering operation by default (``print_report=True``).\nWe will use :py:meth:`xarray.Dataset.update` to update ``ds`` in-place\nwith the filtered ``position``.\n\n"
+        "## Filter out points with low confidence\nUsing the\n:meth:`filter_by_confidence()\\\n<movement.move_accessor.MovementDataset.filtering_wrapper>`\nmethod of the ``move`` accessor,\nwe can filter out points with confidence scores below a certain threshold.\nThe default ``threshold=0.6`` will be used when ``threshold`` is not\nprovided.\nThis method will also report the number of NaN values in the dataset before\nand after the filtering operation by default (``print_report=True``).\nWe will use :meth:`xarray.Dataset.update` to update ``ds`` in-place\nwith the filtered ``position``.\n\n"
       ]
     },
     {
@@ -140,7 +140,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "<div class=\"alert alert-info\"><h4>Note</h4><p>The ``move`` accessor :py:meth:`filter_by_confidence()\\\n   <movement.move_accessor.MovementDataset.filtering_wrapper>`\n   method is a convenience method that applies\n   :py:func:`movement.filtering.filter_by_confidence`,\n   which takes ``position`` and ``confidence`` as arguments.\n   The equivalent function call using the\n   :py:mod:`movement.filtering` module would be:\n\n```python\nfrom movement.filtering import filter_by_confidence\n\nds.update({\"position\": filter_by_confidence(position, confidence)})</p></div>\n```\n"
+        "<div class=\"alert alert-info\"><h4>Note</h4><p>The ``move`` accessor :meth:`filter_by_confidence()\\\n   <movement.move_accessor.MovementDataset.filtering_wrapper>`\n   method is a convenience method that applies\n   :func:`movement.filtering.filter_by_confidence`,\n   which takes ``position`` and ``confidence`` as arguments.\n   The equivalent function call using the\n   :mod:`movement.filtering` module would be:\n\n```python\nfrom movement.filtering import filter_by_confidence\n\nds.update({\"position\": filter_by_confidence(position, confidence)})</p></div>\n```\n"
       ]
     },
     {
@@ -172,7 +172,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Interpolate over missing values\nUsing the\n:py:meth:`interpolate_over_time()\\\n<movement.move_accessor.MovementDataset.filtering_wrapper>`\nmethod of the ``move`` accessor,\nwe can interpolate over the gaps we've introduced in the pose tracks.\nHere we use the default linear interpolation method (``method=linear``)\nand interpolate over gaps of 40 frames or less (``max_gap=40``).\nThe default ``max_gap=None`` would interpolate over all gaps, regardless of\ntheir length, but this should be used with caution as it can introduce\nspurious data. The ``print_report`` argument acts as described above.\n\n"
+        "## Interpolate over missing values\nUsing the\n:meth:`interpolate_over_time()\\\n<movement.move_accessor.MovementDataset.filtering_wrapper>`\nmethod of the ``move`` accessor,\nwe can interpolate over the gaps we've introduced in the pose tracks.\nHere we use the default linear interpolation method (``method=linear``)\nand interpolate over gaps of 40 frames or less (``max_gap=40``).\nThe default ``max_gap=None`` would interpolate over all gaps, regardless of\ntheir length, but this should be used with caution as it can introduce\nspurious data. The ``print_report`` argument acts as described above.\n\n"
       ]
     },
     {
@@ -190,7 +190,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "<div class=\"alert alert-info\"><h4>Note</h4><p>The ``move`` accessor :py:meth:`interpolate_over_time()\\\n   <movement.move_accessor.MovementDataset.filtering_wrapper>`\n   is also a convenience method that applies\n   :py:func:`movement.filtering.interpolate_over_time`\n   to the ``position`` data variable.\n   The equivalent function call using the\n   :py:mod:`movement.filtering` module would be:\n\n```python\nfrom movement.filtering import interpolate_over_time\n\nds.update({\"position\": interpolate_over_time(\n    position_filtered, max_gap=40\n)})</p></div>\n```\n"
+        "<div class=\"alert alert-info\"><h4>Note</h4><p>The ``move`` accessor :meth:`interpolate_over_time()\\\n   <movement.move_accessor.MovementDataset.filtering_wrapper>`\n   is also a convenience method that applies\n   :func:`movement.filtering.interpolate_over_time`\n   to the ``position`` data variable.\n   The equivalent function call using the\n   :mod:`movement.filtering` module would be:\n\n```python\nfrom movement.filtering import interpolate_over_time\n\nds.update({\"position\": interpolate_over_time(\n    position_filtered, max_gap=40\n)})</p></div>\n```\n"
       ]
     },
     {
@@ -233,7 +233,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Filtering multiple data variables\nAll :py:mod:`movement.filtering` functions are available via the\n``move`` accessor. These ``move`` accessor methods operate on the\n``position`` data variable in the dataset ``ds`` by default.\nThere is also an additional argument ``data_vars`` that allows us to\nspecify which data variables in ``ds`` to filter.\nWhen multiple data variable names are specified in ``data_vars``,\nthe method will return a dictionary with the data variable names as keys\nand the filtered DataArrays as values, otherwise it will return a single\nDataArray that is the filtered data.\nThis is useful when we want to apply the same filtering operation to\nmultiple data variables in ``ds`` at the same time.\n\nFor instance, to filter both ``position`` and ``velocity`` data variables\nin ``ds``, based on the confidence scores, we can specify\n``data_vars=[\"position\", \"velocity\"]`` in the method call.\nAs the filtered data variables are returned as a dictionary, we can once\nagain use :py:meth:`xarray.Dataset.update` to update ``ds`` in-place\nwith the filtered data variables.\n\n"
+        "## Filtering multiple data variables\nAll :mod:`movement.filtering` functions are available via the\n``move`` accessor. These ``move`` accessor methods operate on the\n``position`` data variable in the dataset ``ds`` by default.\nThere is also an additional argument ``data_vars`` that allows us to\nspecify which data variables in ``ds`` to filter.\nWhen multiple data variable names are specified in ``data_vars``,\nthe method will return a dictionary with the data variable names as keys\nand the filtered DataArrays as values, otherwise it will return a single\nDataArray that is the filtered data.\nThis is useful when we want to apply the same filtering operation to\nmultiple data variables in ``ds`` at the same time.\n\nFor instance, to filter both ``position`` and ``velocity`` data variables\nin ``ds``, based on the confidence scores, we can specify\n``data_vars=[\"position\", \"velocity\"]`` in the method call.\nAs the filtered data variables are returned as a dictionary, we can once\nagain use :meth:`xarray.Dataset.update` to update ``ds`` in-place\nwith the filtered data variables.\n\n"
       ]
     },
     {