docs(base): fix the angle_std formula and the angle_mean and angle_wrap parameter docs (#253)

## What is wrong

Documentation only, in `spatialmath/base/vectors.py`:

| function | problem | fix |
|---|---|---|
| `angle_std` | the formula has `sin` in both components of the mean
vector; the code (and the correct formula) is `cos` and `sin` |
corrected, and says what `R` is |
| `angle_mean` | the parameter is documented as `v`, it is `theta`; the
range is written `[-\pi, \pi)]` with a stray bracket and the result can
be exactly `\pi` | `theta`, range `[-\pi, \pi]` |
| `angle_wrap` | the parameter is documented as `v`, it is `theta` |
`theta` |

## Added

- `angle_std` is the same quantity as `scipy.stats.circstd` with its
default arguments. I checked this on 300 random samples, the largest
difference is 2e-16.
- a note that `angle_mean` has no defined value when the unit vectors
cancel (for example `0` and `pi`; it returns `pi/2` because of rounding
error)

No code changes.

## Found while checking, not changed here

`angle_std` can return `nan` for a set of identical angles. The mean
resultant length `R` can come out as `1 + 2e-16`, so `-2 * log(R)` is
slightly negative and the square root fails with "invalid value
encountered in sqrt". For example `np.full(100, -2.9)`. I counted 33
failures in 378 combinations of angle and sample size. I will send that
as a separate PR.

Author: petercorke

spatialmath/base/vectors.py

@@ -683,14 +683,28 @@ def angle_std(theta: ArrayLike) -> float:
     r"""
     Standard deviation of angular values
 
-    :param theta: angular values
+    :param theta: angular values, in radians
     :type theta: array_like
-    :return: circular standard deviation
+    :return: circular standard deviation, in radians
     :rtype: float
 
+    The circular standard deviation is
+
     .. math::
 
-        \sigma_{\theta} = \sqrt{-2 \log \| \left[ \frac{\sum \sin \theta_i}{N}, \frac{\sum \sin \theta_i}{N} \right] \|} \in [0, \infty)
+        \sigma_{\theta} = \sqrt{-2 \log R} \in [0, \infty), \quad
+        R = \left\| \left[ \frac{\sum \cos \theta_i}{N}, \frac{\sum \sin \theta_i}{N} \right] \right\|
+
+    where :math:`R` is the length of the mean of the unit vectors at angles
+    :math:`\theta_i`.  :math:`R = 1` if all the angles are equal, giving a
+    standard deviation of zero, and :math:`R \to 0` as the angles spread evenly
+    around the circle, when the standard deviation grows without bound.
+
+    This is the same quantity as ``scipy.stats.circstd`` with its default
+    arguments.
+
+    .. note:: If :math:`R` is exactly zero the result is ``inf``, with a NumPy
+        divide-by-zero warning.
 
     :seealso: :func:`angle_mean`
     """
@@ -708,16 +722,23 @@ def angle_mean(theta: ArrayLike) -> float:
     r"""
     Mean of angular values
 
-    :param theta: angular values
-    :type v: array_like
-    :return: circular mean
+    :param theta: angular values, in radians
+    :type theta: array_like
+    :return: circular mean, in radians
     :rtype: float
 
-    The circular mean is given by
+    The circular mean is the angle of the mean of the unit vectors at angles
+    :math:`\theta_i`
 
     .. math::
 
-        \bar{\theta} = \tan^{-1} \frac{\sum \sin \theta_i}{\sum \cos \theta_i} \in [-\pi, \pi)]
+        \bar{\theta} = \tan^{-1} \frac{\sum \sin \theta_i}{\sum \cos \theta_i} \in [-\pi, \pi]
+
+    computed with the two-argument arctangent so that the quadrant is correct.
+
+    .. note:: If the unit vectors cancel, for example the angles :math:`0` and
+        :math:`\pi`, the mean direction is undefined and the result is decided by
+        rounding error.
 
     :seealso: :func:`angle_std`
     """
@@ -730,8 +751,8 @@ def angle_wrap(theta: ArrayLike, mode: str = "-pi:pi") -> Union[float, NDArray]:
     """
     Generalized angle-wrapping
 
-    :param v: angles to wrap
-    :type v: array_like
+    :param theta: angles to wrap
+    :type theta: array_like
     :param mode: wrapping mode, one of: ``"0:2pi"``, ``"0:pi"``, ``"-pi/2:pi/2"`` or ``"-pi:pi"`` [default]
     :type mode: str, optional
     :return: wrapped angles