Add blog post about displacement's API changes (#688)

* Add draft for post about displacement's API changes

* remove reference to v0.0.13

Co-authored-by: Niko Sirmpilatze <[email protected]>

* improve phrasing in compute_displacement introduction

Co-authored-by: Niko Sirmpilatze <[email protected]>

* improve wording talking about the PR

Co-authored-by: Niko Sirmpilatze <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* compute_backward_displacement

Co-authored-by: Niko Sirmpilatze <[email protected]>

* improve wording on cart2pol

Co-authored-by: Niko Sirmpilatze <[email protected]>

* blog: change title and add 1-sentence summary

* blog: better explaination of how old implementation worked

* blog: headings changes

* blog: improve suggestion on how to transition to the new API

Co-authored-by: Niko Sirmpilatze <[email protected]>

* update date and headings

* linkcheck ignore BraiAn

---------

Co-authored-by: Niko Sirmpilatze <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/source/blog/displacement-vectors.md

@@ -0,0 +1,56 @@
+---
+blogpost: true
+date: November 7, 2025
+author: Carlo Castoldi
+location: Milan, Italy
+category: update
+language: English
+---
+
+# Replacing displacement vectors for greater clarity
+
+This post introduces recent improvements to how ``movement`` computes displacement vectors, making the definitions more explicit, flexible, and intuitive for users.
+
+## Background
+
+Computing kinematic properties is a core functionality since early versions of `movement`, when they where first introduced by [Chang Huan Lo](https://github.com/lochhh) in [#106](https://github.com/neuroinformatics-unit/movement/pull/106).
+For a library dedicated to analysing motion-tracking data, quantifying how far a tracked point moves between consecutive frames is fundamental. This measure underpins subsequent computations, such as the total distance travelled along a path. That's why we introduced the `compute_displacement` function early on, and why it features in our {ref}`compute and visualise kinematics <sphx_glr_examples_compute_kinematics.py>` example<!--#compute-displacement-vectors heading-->.
+
+Its original implementation, however, produced results that were difficult to interpret. For a given individual and keypoint at timestep `t`, displacement was defined as the vector pointing from the previous position at `t-1` to the current position at `t`. This definition is somewhat counter-intuitive: it identifies the last spatial translation used by the keypoint to reach its current position. It indicates where the point _came from_ rather than where it is _going_.
+
+For this reason, during the Hackday at [Open Software Week 2025](https://neuroinformatics.dev/open-software-summer-school/2025/index.html)—and as my first contribution to `movement`—I [volunteered](https://github.com/neuroinformatics-unit/osw25-hackday/issues/16) to develop a more intuitive interface for displacement vectors, under the supervision of [Sofía Miñano](https://github.com/sfmig).
+These improvements were introduced in [#657](https://github.com/neuroinformatics-unit/movement/pull/657) through a collaborative effort. The update provides a simpler, well-tested, and better-documented implementation that makes displacement computations easier to understand and use.
+
+![A diagram that shows the comparison between the previous implementation and the updated one.](resources/displacement_old_vs_new.png)
+
+## What's new?
+
+{mod}`kinematics <movement.kinematics>` has two new sister functions:
+
+- {func}`compute_forward_displacement <movement.kinematics.compute_forward_displacement>`, computing the vector defined at time `t` that goes from the position in the current frame to the position in the next frame, at `t+1`.
+- {func}`compute_backward_displacement <movement.kinematics.compute_backward_displacement>`, computing the vector defined at time `t` that goes from the position in the current frame to the position in the previous frame, at `t-1`.
+
+These functions replace the previous, more ambiguous `compute_displacement`, which has now been deprecated.
+The new API makes the directionality of displacement **explicit**, giving users greater **flexibility**. Depending on the context, one can now choose between forward- or backward-oriented vectors instead of relying on a single implicit definition.
+
+If you need a drop-in replacement for the old behaviour, you can use:
+
+  ```python
+  import movement.kinematics as kin
+
+  # Instead of:
+  displacement = kin.compute_displacement(ds.position)
+
+  # Use:
+  displacement = -kin.compute_backward_displacement(ds.position)
+  ```
+
+__Related changes__
+
+We slightly modified the behaviour of vector conversion from Cartesian to polar coordinates. For simplicity and interpretability, {func}`cart2pol <movement.utils.vector.cart2pol>` now always sets the angle `phi` to 0 when the vector's norm `rho` is 0, rather than following the [C standard](https://www.iso.org/standard/29237.html) for [`arctan2`](https://en.wikipedia.org/wiki/Atan2). This change should not affect existing workflows, as a zero-length vector has an undefined direction—meaning it could point in any direction, and assigning `phi = 0` is a safe, neutral choice.
+
+## Reflections
+
+I would like to extend my sincere gratitude to the [Neuroinformatics Unit](https://neuroinformatics.dev/) for fostering an exceptional open environment that has even inspired me to enhance my own projects. Their efforts have motivated me to make [BraiAn](https://silvalab.codeberg.page/BraiAn/) more accessible to inexperienced researchers, to improve its interoperability and to develop automated pipelines for software verification.
+
+I am firmly convinced that bridging the gap between experimental laboratories is crucial for enabling reproducible and comparable results across research groups. I have long _believed_ that the development and adoption of shared standards and widely accepted platforms can facilitate this goal. The Neuroinformatics Unit has not only reinforced my conviction but also _demonstrated_, through their remarkable work, that this vision can be turned into a practical reality.

docs/source/blog/resources/displacement_old_vs_new.png

@@ -191,6 +191,7 @@
     "https://opensource.org/license/bsd-3-clause/",  # to avoid odd 403 error
     "https://www.sainsburywellcome.org/",  # Occasional ConnectTimeoutError
     "https://www.robots.ox.ac.uk/",  # occasional 404s
+    "https://silvalab.codeberg.page/BraiAn/",  # SSLError despite working link
 ]
 
 

docs/source/conf.py

@@ -198,8 +198,9 @@
 ax.set_ylim(980, 1080)
 ax.set_xlabel("x (pixels)")
 ax.set_ylabel("y (pixels)")
-ax.set_title(f"Zoomed in trajectory of {mouse_name}")
+ax.set_title(f"Zoomed in forward trajectory of {mouse_name}")
 ax.invert_yaxis()
+sc.set_clim(8.8, 9.2)
 fig.colorbar(sc, ax=ax, label="time (s)")
 
 
@@ -250,8 +251,9 @@
 ax.set_ylim(980, 1080)
 ax.set_xlabel("x (pixels)")
 ax.set_ylabel("y (pixels)")
-ax.set_title(f"Zoomed in trajectory of {mouse_name}")
+ax.set_title(f"Zoomed in backward trajectory of {mouse_name}")
 ax.invert_yaxis()
+sc.set_clim(8.8, 9.2)
 fig.colorbar(sc, ax=ax, label="time (s)")