Add references

docs/source/getting_started/movement_dataset.md

@@ -195,7 +195,7 @@ For example, you can:
 [data aggregation and broadcasting](xarray:user-guide/computation.html), and
 - use `xarray`'s built-in [plotting methods](xarray:user-guide/plotting.html).
 
-As an example, here's how you can use the `sel` method to select subsets of
+As an example, here's how you can use {meth}`xarray.Dataset.sel` to select subsets of
 data:
 
 ```python
@@ -246,12 +246,11 @@ ds["velocity"] = compute_velocity(ds.position)
 ds.velocity
 ```
 
-The output of `compute_velocity()` is an {class}`xarray.DataArray` object,
+The output of {func}`movement.analysis.kinematics.compute_velocity` is an {class}`xarray.DataArray` object,
 with the same **dimensions** as the original `position` **data variable**,
 so adding it to the existing `ds` makes sense and works seamlessly.
 
-We can also update existing **data variables** in-place, using the `update()`
-method. For example, if we wanted to update the `position`
+We can also update existing **data variables** in-place, using {meth}`xarray.Dataset.update`. For example, if we wanted to update the `position`
 and `velocity` arrays in our dataset, we could do:
 
 ```python

examples/compute_kinematics.py

@@ -117,17 +117,19 @@
 # %%
 # Compute displacement
 # ---------------------
+# The :mod:`movement.analysis.kinematics` module provides functions to compute
+# various kinematic quantities,
+# such as displacement, velocity, and acceleration.
 # We can start off by computing the distance travelled by the mice along
-# their trajectories.
-# For this, we can use the ``compute_displacement()`` function from
-# the :mod:`movement.analysis.kinematics` module:
+# their trajectories:
 
 import movement.analysis.kinematics as kin
 
 displacement = kin.compute_displacement(position)
 
 # %%
-# This function will return a data array equivalent to the ``position`` one,
+# The :func:`movement.analysis.kinematics.compute_displacement`
+# function will return a data array equivalent to the ``position`` one,
 # but holding displacement data along the ``space`` axis, rather than
 # position data.
 #
@@ -267,7 +269,8 @@
 velocity = kin.compute_velocity(position)
 
 # %%
-# The ``compute_velocity()`` function will return a data array equivalent to
+# The :func:`movement.analysis.kinematics.compute_velocity`
+# function will return a data array equivalent to
 # the ``position`` one, but holding velocity data along the ``space`` axis,
 # rather than position data. Notice how ``xarray`` nicely deals with the
 # different individuals and spatial dimensions for us! ✨
@@ -343,7 +346,8 @@
 # %%
 # Compute acceleration
 # ---------------------
-# We can compute the acceleration of the data with an equivalent method:
+# Let's now compute the acceleration for all individuals in our data
+# array:
 accel = kin.compute_acceleration(position)
 
 # %%
@@ -368,8 +372,8 @@
 fig.tight_layout()
 
 # %%
-# The can also represent the magnitude (norm) of the acceleration vector
-# for each individual:
+# We can also compute and visualise the magnitude (norm) of the
+# acceleration vector for each individual:
 fig, axes = plt.subplots(3, 1, sharex=True, sharey=True)
 for mouse_name, ax in zip(accel.individuals.values, axes, strict=False):
     # compute magnitude of the acceleration vector for one mouse