ENH: [feature requests] adding basic angle statistics and modular operation functions

Is your feature request related to a problem? Please describe. NumPy and SciPy has many useful functions about angle like:

• Numpy’s Trigonometric functions: https://numpy.org/doc/1.18/reference/routines.math.html#trigonometric-functions
• Scipy’s scipy.spatial.transform.Rotation https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html

However, I think there are some basic functions are still missing. For example, basic angle statistics (diff, mean, std) and modular operation functions making angles between [-pi, pi) or [0, 2pi). I think these functions are very useful for many science and engineering field especially in robotics, control, etc. So, I think it would be great if SciPy (or NumPy?) has some additional basic angle functions.

What do you guys think this idea?

Describe the solution you’d like Adding new simple functions like below:

Angle mean calculation function

def angle_mean(x, degree=False):
    """
    Calculate mean of angles.

    Parameters
    ----------
    x : array_like
        Array of angles. This array is flattened for the calculation.
    degree : bool, optional
        If True, then the given angles are assumed to be in degrees.
        Default is False.

    Returns
    -------
    ret : float
        the mean of angles

    Examples
    --------
    >>> angle_mean([0.0, 1.0, 2.0, 4.0, 5.0])
    0.04643020836284735

    >>> angle_mean([0.0, 90.0, -90.0], degree=True)
    0.0

    """
    x_flat = np.asarray(x).flatten()
    if degree:
        x_flat = np.deg2rad(x_flat)
    mean_angle = np.arctan2(sum(np.sin(x_flat)), sum(np.cos(x_flat)))
    if degree:
        mean_angle = np.rad2deg(mean_angle)
    return mean_angle

Angle difference calculation function

def angle_diff(x, degree=False):
    """
    Calculate differences of angles.

    Parameters
    ----------
    x : array_like
        Array of 1D angles. This array is flattened for the calculation.
    degree : bool, optional
        If True, then the given angles are assumed to be in degrees.
        Default is False.

    Returns
    -------
    ret : ndarray
        Array of differential angles.

    Examples
    --------
    >>> angle_diff([1.0, 2.0, -2.0, 2.0])
    array([1., 2.28318531, -2.28318531])

    >>> angle_diff([100, 200, -200, 100], degree=True)
    array([100., -40., -60.])

    """
    x = np.asarray(x).flatten()
    if degree:
        x = np.deg2rad(x)
    x_diff = np.diff(x)
    diff_angles = np.arctan2(np.sin(x_diff), np.cos(x_diff))
    if degree:
        diff_angles = np.rad2deg(diff_angles)
    return diff_angles

Angle standard deviation calculation function

def angle_std(x, degree=False):
    """
    Calculate standard deviations of angles.


    Parameters
    ----------
    x : float or array_like
        Array of angles. This array is flattened for the calculation.
    degree : bool, optional
        If True, then the given angles are assumed to be in degrees.
        Default is False.

    Returns
    -------
    ret : float
        the standard deviation of angles

    Examples
    --------
    >>> angle_std([-170.0, 170.0, 175], degree=True)
    8.49838204876532

    >>> angle_std([-170.0, 170], degree=True)
    9.999999999999995

    >>> angle_std(-1.0)
    0.0

    """
    x = np.asarray(x).flatten()
    if degree:
        x = np.deg2rad(x)
    mean_angle = angle_mean(x)
    diff_angles = np.array([angle_diff([ix, mean_angle]) for ix in x])
    std_angle = np.sqrt(np.mean((diff_angles**2)))
    if degree:
        std_angle = np.rad2deg(std_angle)
    return std_angle

Angle modulo operation function

def angle_mod(x, zero_2_2pi=False, degree=False):
    """
    Angle modulo operation
    Default angle modulo range is [-pi, pi)

    Parameters
    ----------
    x : float or array_like
        Array of angles. This array is flattened for the calculation.
    zero_2_2pi : bool, optional
        Change angle modulo range to [0, 2pi)
        Default is False.
    degree : bool, optional
        If True, then the given angles are assumed to be in degrees.
        Default is False.

    Returns
    -------
    ret : ndarray
        Array of modulated angles.

    Examples
    --------
    >>> angle_mod(-4.0)
    array([2.28318531])

    >>> angle_mod([-150.0, 190.0, 350], degree=True)
    array([-150., -170.,  -10.])

    >>> angle_mod(-60.0, zero_2_2pi=True, degree=True)
    array([300.])

    """
    x = np.asarray(x).flatten()
    if degree:
        x = np.deg2rad(x)
    if zero_2_2pi:
        mod_angle = x % (2 * np.pi)
    else:
        mod_angle = (x + np.pi) % (2 * np.pi) - np.pi
    if degree:
        mod_angle = np.rad2deg(mod_angle)
    return mod_angle

[Make42]

I would also be very interested if this could be done for high dimensional coordinate systems, esp. spherical <-> cartesian for systems with dimension larger than 3.

[WarrenWeckesser]

FYI: We have circmean, circvar and circstd in stats: https://docs.scipy.org/doc/scipy/reference/stats.html#circular-statistical-functions