pingouin.convert_angles#

pingouin.convert_angles(angles, low=0, high=360, positive=False)[source]#

Element-wise conversion of arbitrary-unit circular quantities to radians.

Added in version 0.3.4.

Parameters:
anglesarray_like

Circular data.

lowfloat or int, optional

Low boundary for angles range. Default is 0.

highfloat or int, optional

High boundary for angles range. Default is 360 (for degrees to radians conversion).

positiveboolean

If True, radians are mapped on the \([0, 2\pi]\). Otherwise, the resulting angles are mapped from \([-\pi, \pi)\) (default).

Returns:
radiansarray_like

Circular data in radians.

Notes

The formula to convert a set of angles \(\alpha\) from an arbitrary range \([\text{high},\text{low}]\) to radians \([0, 2\pi]\) is:

\[\alpha_r = \frac{2\pi\alpha}{\text{high} - \text{low}}\]

If positive=False (default), the resulting angles in radians \(\alpha_r\) are then wrapped to the \([-\pi, \pi)\) range:

\[(\text{angle} + \pi) \mod 2 \pi - \pi\]

Examples

  1. Convert degrees to radians

>>> from pingouin import convert_angles
>>> a = [0, 360, 180, 90, 45, 270]
>>> convert_angles(a, low=0, high=360)
array([ 0.        ,  0.        , -3.14159265,  1.57079633,  0.78539816,
       -1.57079633])

with positive=True:

>>> convert_angles(a, low=0, high=360, positive=True)
array([0.        , 6.28318531, 3.14159265, 1.57079633, 0.78539816,
       4.71238898])

  1. Convert hours (24h-format) to radians

>>> sleep_onset = [22.5, 23.25, 24, 0.5, 1]
>>> convert_angles(sleep_onset, low=0, high=24)
array([-0.39269908, -0.19634954,  0.        ,  0.13089969,  0.26179939])

  1. Convert radians from \([0, 2\pi]\) to \([-\pi, \pi)\):

>>> import numpy as np
>>> rad = [0.1, 3.14, 5, 2, 6]
>>> convert_angles(rad, low=0, high=2*np.pi)
array([ 0.1       ,  3.14      , -1.28318531,  2.        , -0.28318531])

  1. Convert degrees from a 2-D array

>>> np.random.seed(123)
>>> deg = np.random.randint(low=0, high=360, size=(3, 4))
>>> convert_angles(deg)
array([[-0.66322512,  1.71042267, -2.26892803,  0.29670597],
       [ 1.44862328,  1.85004901,  2.14675498,  0.99483767],
       [-2.54818071, -2.35619449,  1.67551608,  1.97222205]])